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Preface 


The  IBM  Personal  Computer  BASIC  interpreter 
consists  of  three  upward  compatible  versions: 
Cassette,  Disk,  and  Advanced.  This  manual  is  a 
reference  for  all  three  versions  of  BASIC  release 
1.10.  We  shall  use  the  general  term  "BASIC"  in  this 
book  to  refer  to  any  of  the  versions  of  BASIC  — 
Cassette,  Disk,  or  Advanced. 

The  IBM  Personal  Computer  BASIC  Compiler  is  an 
optional  software  package  available  from  IBM.  If 
you  have  the  BASIC  Compiler,  the  IBM  Personal 
Computer  Basic  Compiler  manual  is  used  in  conjunction 
with  this  book  for  reference. 
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How  to  Use  This  Manual 


In  order  to  use  this  manual,  you  should  have  some 
knowledge  of  general  programming  concepts;  we 
are  not  trying  to  teach  you  how  to  program  in  this 
manual. 

The  manual  is  divided  into  four  chapters  plus  a 
number  of  appendices. 

Chapter  1  is  a  brief  overview  of  the  three 
versions  of  IBM  Personal  Computer  BASIC. 

Chapter  2  tells  you  what  you  need  to  know  to 
start  using  BASIC  on  your  IBM  Personal 
Computer.  It  tells  you  how  to  operate  your 
computer  using  BASIC. 

Chapter  3  covers  a  variety  of  topics  which  you 
will  need  to  know  before  you  actually  start 
programming.  Much  of  the  information 
pertains  to  data  representation  when  using 
BASIC.  We  discuss  filenames  here,  along  with 
many  of  the  special  input  and  output  features 
available  in  IBM  Personal  Computer  BASIC. 

Chapter  4  is  the  reference  section.  It  contains 
the  syntax  and  semantics  of  every  command, 
statement,  and  function  in  BASIC,  ordered 
alphabetically. 

The  appendices  contain  other  useful 
information,  such  as  lists  of  error  messages, 
ASCII  codes,  and  math  functions;  and  helpful 
information  on  machine  language  subroutines, 
diskette  input  and  output,  and 
communications.  You  can  also  find  detailed 
information  on  more  advanced  subjects  for  the 
more  experienced  programmer. 

We  suggest  you  read  through  all  of  chapters  2  and  3 
to  become  familiar  with  BASIC.  Then  you  can  refer 
to  chapter  4  while  you  are  actually  programming  to 
get  information  you  need  about  each  command  or 
statement  that  you  use. 


Syntax  Diagrams 


Each  of  the  commands,  statements,  and  functions 
described  in  this  book  has  its  syntax  described 
according  to  the  following  conventions: 

•  Words  in  capital  letters  are  keywords  and  must 

be  entered  as  shown.  They  may  k  entered  in 

any  combination  of  uppercase  and  lowercase. 
BASIC  always  C(?nY€rtS  words  to  uppercase 
(unless  they  are  part  of  a  quoted  string,  remark, 
or  DATA  statement). 

•  You  must  supply  any  items  in  lowercase  italic 
letters. 

•  Items  in  square  brackets  (  [  ]  )  are  optional. 

•  An  ellipsis  (.  .  .)  indicates  an  item  may  be 
repeated  as  many  times  as  you  wish. 

•  All  punctuation  except  square  brackets  (such  as 
commas,  parentheses,  semicolons,  hyphens,  or 
equal  signs)  must  be  included  where  shown. 

Let's  look  at  an  example: 

INPUT [;]["/> rompf ' ; ]  variable^ variable] . . . 

This  says  that  for  an  INPUT  statement  to  be  valid, 
you  must  first  have  the  keyword  INPUT,  followed 
optionally  by  a  semicolon.  Then,  if  you  wish,  you 
may  include  a  prompt  within  quotation  marks.  If  you 
do  include  the  prompt,  it  must  be  followed  by  a 
semicolon.  At  least  one  variable  is  required  for  an 
INPUT  statement.  You  may  have  more  than  one 
variable  if  you  separate  them  with  commas. 

More  detailed  information  on  each  of  the 
parameters  is  included  with  the  text  accompanying 
the  diagram.  The  information  for  this  example  is  in 
Chapter  4,  under  "INPUT  Statement." 
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Related  Publications 

The  following  manuals  contain  related  information 
that  you  may  find  useful: 

•  The  IBM  Personal  Computer  Guide  to  Operations 
manual. 

•  The  IBM  Personal  Computer  Disk  Operating  System 
manual. 

•  The  IBM  Personal  Computer  Technical  Reference 
manual. 
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The  Versions  of  BASIC 


The  IBM  Personal  Computer  offers  three  differen 
versions  of  the  BASIC  interpreter: 

•  Cassette 

•  Disk 

•  Advanced 

The  three  versions  of  BASIC  are  upward  compatible; 
that  is,  Disk  BASIC  does  everything  Cassette  BASIC 
does,  plus  a  little  more,  and  Advanced  BASIC  does 
everything  Disk  BASIC  does,  plus  a  little  more.  The 
differences  between  the  versions  are  discussed  in 
more  detail  below. 

The  BASIC  commands,  statements,  and  functions 
for  all  three  versions  of  the  BASIC  interpreter  are 
described  in  detail  in  "Chapter  4.  BASIC  Commands, 
Statements,  Functions,  and  Variables."  Included  in 
each  description  is  a  section  called  Versions:,  where 
we  tell  you  which  versions  of  BASIC  support  the 
command,  statement,  or  function. 

For  example,  if  you  look  under  "CHAIN  Statement" 
in  Chapter  4,  you  will  note  that  it  says: 


Versions:  Cassette  Disk         Advanced  Compiler 

***  ***  (**) 

The  asterisks  indicate  which  versions  of  BASIC 
support  the  statement.  This  example  shows  that  you 
can  use  the  CHAIN  statement  for  programs  written 
in  the  Disk  and  Advanced  versions  of  BASIC. 

In  this  example  you  will  notice  that  the  asterisks 
under  the  word  "Compiler"  are  in  parentheses.  This 
means  that  there  are  differences  between  the  way  the 
statement  works  under  the  BASIC  interpreter  and 
the  way  it  works  under  the  IBM  Personal  Computer 
BASIC  Compiler.  The  IBM  Personal  Computer 
BASIC  Compiler  is  an  optional  software  package 
available  from  IBM.  If  you  have  the  BASIC 
Compiler,  the  IBM  Persona/  Computer  BASIC  Compiler 
manual  explains  these  differences. 
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Cassette  BASIC 


The  nucleus  of  BASIC  is  the  Cassette  version,  which 
is  built  into  your  IBM  Personal  Computer  in 
32K-bytes  of  read-only  storage.  You  can  use 
Cassette  BASIC  on  an  IBM  Personal  Computer  with 
any  amount  of  random  access  memory.  The  amount 
of  storage  you  can  use  for  such  things  as  programs 
and  data  depends  on  how  much  memory  you  have  in 
your  IBM  Personal  Computer.  The  number  of 
"bytes  free"  will  be  displayed  after  you  switch  on  the 
computer. 

The  only  storage  device  you  can  use  to  save 
information  in  Cassette  BASIC  is  a  cassette  tape 
recorder.  You  cannot  use  diskettes  with  Cassette 
BASIC. 

Some  special  features  you  will  find  in  this  and  the 
other  two  versions  of  BASIC  are: 

•  An  extended  character  set  of  256  different 
characters  which  can  be  displayed.  In  addition 
to  the  usual  letters,  numbers,  and  special 
symbols,  you  also  have  international  characters 
like  n,  a,  and  i.  You  will  also  find  symbols  which 
are  commonly  used  in  scientific  and 
mathematical  applications,  such  as  Greek 
letters.  There  are  also  a  variety  of  other 
symbols. 

•  Graphics  capability.  If  you  have  the 

Color/ Graphics  Monitor  Adapter,  you  can  draw 
points,  lines,  and  even  entire  pictures.  The 
screen  can  be  all  points  addressable  in  either 
medium  or  high  resolution.  More  information 
on  this  can  be  found  in  Chapter  3. 

•  Special  input/output  devices.  The  IBM 
Personal  Computer  has  a  speaker  which  you  can 
use  to  make  sound.  Also,  BASIC  supports  a  light 
pen  and  joysticks  which  help  make  your 
programs  more  interesting  as  well  as  more  fun. 
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Disk  BASIC 


This  version  of  BASIC  comes  as  a  program  on  the 

MrmoiIGoiutcrMCpfiniPjiffm 

(DOS)  diskette.  DOS  is  a  separate  product  available 
from  IBM.  You  have  to  load  Disk  BASIC  into 
memory  before  you  can  use  it.  Disk  BASIC  requires  a 
diskette-based  machine  with  at  least  32K-bytes  of 
random  access  memory.  The  amount  of  storage  you 
can  use  for  such  things  as  programs  and  data  is 
displayed  on  the  screen  when  you  start  BASIC. 

Special  features  of  Disk  BASIC  are: 

•  Input/output  to  diskette  in  addition  to  cassette. 
See  "Appendix  B.  BASIC  Diskette  Input  and 
Output"  for  special  considerations  when  using 
diskette  files. 

•  An  internal  "clock,"  which  keeps  track  of  the 
date  and  time. 

•  Asynchronous  communications  (RS2  32) 
support,  which  you  can  use  if  you  have  an 
Asynchronous  Communications  Adapter. 
Refer  to  "Appendix  F.  Communications"  for 
details. 

•  Support  for  two  additional  printers. 
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Advanced  BASIC 


Advanced  BASIC,  the  most  extensive  form  of  BASIC 
available  on  the  IBM  Personal  Computer,  does 
everything  that  Cassette  and  Disk  BASIC  do,  and 
more.  Like  Disk  BASIC,  it  is  a  program  on  the  IBM 
DOS  diskette  which  you  must  load  into  memory  to 
use.  Advanced  BASIC  requires  a  diskette-based 
machine  with  at  least  48K-bytes  of  random  access 
memory.  As  with  the  other  versions,  the  number  of 
free  bytes  you  will  have  for  programs  and  data  is 
displayed  on  the  screen  when  you  start  BASIC. 

Key  features  found  only  in  Advanced  BASIC  are  the 
following: 

•  Event  trapping.  A  program  can  respond  to  the 
occurrence  of  a  specific  event  by  "trapping" 
(automatically  branching)  to  a  specific  program 
line.  Events  include:  communications  activity, 
a  function  key  being  pressed,  the  button  being 
pressed  on  a  joystick,  and  the  light  pen  being 
activated. 

•  Advanced  graphics.  Additional  statements  are 
CIRCLE,  PUT,  GET,  PAINT,  and  DRAW. 
These  operations  make  it  easier  to  create  more 
complex  graphics  with  the  Color/Graphics 
Monitor  Adapter. 

•  Advanced  music  support.  The  PLAY  statement 
allows  easy  usage  of  the  built-in  speaker  to 
create  musical  tones. 
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Getting  BASIC  Started 


It's  easy  to  start  BASIC  on  the  IBM  Personal 
Computer: 

To  Start  Cassette  BASIC: 

Just  switch  the  computer  on.  If  your  system  has 
diskette  drives,  you  should  make  sure  you  don't  have 
a  diskette  in  drive  A,  or  leave  the  drive  door  open. 

The  words  "Version  C"  and  the  release  number  will 
be  displayed  along  with  the  number  of  free  bytes  you 
have  available. 

To  Start  Disk  BASIC: 

1.  Start  DOS.  To  do  this,  you  can: 

a.  Insert  the  IBM  DOS  diskette  in  drive  A:. 

b.  Switch  on  the  computer. 

2.  Enter  the  command  BASIC  when  DOS  prompts 
you  for  a  command. 

The  words  "Version  D"  and  the  release  number 
will  be  displayed  along  with  the  number  of  free 
bytes. 

To  Start  Advanced  BASIC: 

1.  Start  DOS  as  described  above. 

2.  Enter  the  command  BASICA  in  response  to  the 
DOS  prompt. 

The  words  "Version  A"  and  the  release  number 
will  be  displayed  along  with  the  number  of  free 
bytes. 
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Options  on  the  BASIC  Command 


You  can  include  options  on  the  BASIC  or  BASICA 
command  when  you  start  Disk  or  Advanced  BASIC. 
These  options  specify  the  amount  of  storage  BASIC 
uses  to  hold  programs  and  data,  and  for  buffer  areas. 
You  can  also  ask  BASIC  to  immediately  load  and  run 
a  program. 

These  options  are  not  required — BASIC  will  work 
just  fine  without  them.  So  if  you're  new  to  BASIC, 
you  may  wish  to  skip  over  this  section  and  go  on  to 
the  next  section,  "Modes  of  Operation."  Then  you 
can  refer  back  to  this  section  when  you  become 
more  familiar  with  BASIC  and  its  capabilities. 

The  complete  format  of  the  BASIC  command  is: 

BASIQA]  [f/Iespec]  [/Fifties]  [/Sibsize] 
[/Q:com  buffer]  [/M:max  workspace] 

f/lespec  is  the  file  specification  of  a  program  to  be 
loaded  and  executed  immediately.  It  must  be  a 
character  string  constant,  but  it  should  not  be 
enclosed  in  quotation  marks.  It  should  conform  to 
the  rules  for  specifying  files  described  under 
"Naming  Files"  in  "Chapter  3.  General  Information 
about  Programming  in  BASIC."  A  default  extension 
of  .BAS  is  used  if  none  is  supplied  and  the  length  of 
the  filename  is  eight  characters  or  less.  If  you  include 

filespec,  BASIC  proceeds  as  if  a  KUNfi/espec  command 
were  the  first  thing  you  entered  once  BASIC  is  ready. 
Note  that  when  you  specify  filespec,  the  BASIC 
heading  with  the  copyright  notices  is  not  displayed. 

lYfi/es  sets  the  maximum  number  of  files  that  may 
be  open  at  any  one  time  during  the  execution  of  a 
BASIC  program.  Each  file  requires  188  bytes  of 
memory  for  the  file  control  block,  plus  the  buffer 
size  specified  in  the  /S:  option.  If  the  /F:  option  is 
omitted,  the  number  of  files  defaults  to  three.  The 
maximum  value  is  15. 
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msize  sets  the  buffer  size  for  use  with  random  files 
I  he  record  length  parameter  on  the  OPEN 
statement  may  not  exceed  this  value.  The  default 
buffer  size  is  128  bytes.  The  maximum  value  you 

mYenter,s  3276f-  wffHfptyfliiiiacffi:]izfor 

improved  performance  when  using  random  files. 

IQ.combuffer  sets  the  size  of  the  buffer  for  receiving 
data  when  using  the  Asynchronous 
Communications  Adapter.  This  option  has  no  effect 
unless  you  have  an  Asynchronous  Communications 
Adapter  on  your  system.  The  buffer  for  transmitting 
data  with  communications  is  always  allocated  to  1 28 
bytes.  The  maximum  value  you  may  enter  for  the/C: 
option  is  32767.  If  the  /C:  option  is  omitted,  256 
bytes  are  allocated  for  the  receive  buffer.  If  you  have 
a  high-speed  line,  we  suggest  you  use/C:1024.  If  you 
have  two  Asynchronous  Communications  Adapters 
on  your  system,  both  receive  buffers  are  set  to  the 
size  specified  by  this  option.  You  may  disable  RS232 
support  by  using  a  value  of  zero  (/C:0),  in  which  case 
no  buffer  space  will  be  reserved  for 
communications,  and  communications  support  will 
not  be  included  when  BASIC  is  loaded. 


/M:max  workspace  sets  the  maximum  number  of  bytes 
that  may  be  used  as  BASIC  workspace.  BASIC  is  only 
able  to  use  a  maximum  of  64K-bytes  of  memory,  so 
the  highest  value  you  may  set  is  64K  (hex  FFFF). 
You  can  use  this  option  in  order  to  reserve  space  for 
machine  language  subroutines  or  for  special  data 
storage.  You  may  wish  to  refer  to  "Memory  Map"  in 
Appendix  I  for  more  detailed  information  on  how 
BASIC  uses  memory.  If  the/M:  option  is  omitted,  all 
available  memory  up  to  a  maximum  of  64K-bytes  is 
used. 


Note:   files,  max  workspace,  bsize,  and  combuffer 
are  all  numbers  that  may  be  either  decimal, 
octal  (preceded  by  &O)  or  hexadecimal 
(preceded  by  &H). 
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Some  examples  of  using  the  BASIC  command: 


t       h.    i  •  ■  r  KO L  !  ,  b / 1 

This  will  start  Disk  BASIC  so  that  it  will  use  the 
defaults  as  just  described  —  all  memory  and 
three  files.  The  program  PAYROLL. BAS  will 
be  loaded  and  executed. 


Here  we  start  Advanced  BASIC  to  use  all 
memory  and  six  files,  and  load  and  execute 
INVEN.BAS.  Remember,  .BAS  is  the  default 
extension. 


This  command  starts  Disk  BASIC  so  the 
maximum  workspace  size  is  32768.  That  is, 
BASIC  will  use  only  32K-bytes  of  memory.  No 
more  than  three  files  will  be  used  at  one  time. 


This  command  sets  the  maximum  workspace 
size  to  hex  9000.  This  means  Advanced  BASIC 
will  be  able  to  use  up  to  36K-bytes  of  memory. 
Also,  file  control  blocks  are  set  up  for  two  files, 
and  the  program  CHKWRR.TST  on  the 
diskette  in  drive  B  is  loaded  and  executed. 


Modes  of  Operation 


Once  BASIC  is  started,  it  displays  the  prompt  Ok. 
Ok  means  BASIC  is  ready  for  you  to  tell  it  what  to  do. 
Sometimes  this  state  is  known  as  command  level.  At 
this  point,  you  may  talk  to  BASIC  in  either  of  two 
moH  2s:  the  direct  mode  or  the  indirect  mode. 


Indirect  Mode 

You  enter  programs  using  indirect  mode.  To  tell 
BASIC  the  line  you  are  entering  is  part  of  a  program, 
you  begin  the  line  with  a  line  number.  The  line  is  then 
stored  as  part  of  the  program  in  memory.  The 
program  in  storage  can  be  executed  by  entering  the 
RUN  command.  For  example: 


1    PR! h  r  20 ; I 

'A  !  J  N 


Direct  Mode 

Direct  mode  means  you  are  telling  BASIC  to  perform 
your  request  immediately  after  the  request  is 
entered.  You  tell  BASIC  to  do  this  by  not  preceding 
the  statement  or  command  with  a  line  number.  You 
can  display  results  of  arithmetic  and  logical 
operations  immediately  or  store  them  for  later  use, 
but  the  instructions  themselves  are  not  saved  after 
they  are  executed.  This  mode  is  useful  for  debugging 
as  well  as  for  quick  computations  that  do  not  require 
a  complete  program.  For  example: 


2-7 


The  Keyboard 
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The  keyboard. is  divided  into  three  general  areas: 

•  Ten  function  keys,  labeled  Fl  through  FlO,  are 
on  the  left  side  of  the  keyboard. 

•  The  "typewriter"  area  is  in  the  middle.  This  is 
where  you  find  the  regular  letter  and  number 
keys. 

•  The  numeric  keypad,  similar  to  a  calculator 
keyboard,  is  on  the  right  side. 

All  the  keys,  in  all  three  areas  of  the  keyboard,  are 
typematic.  That  means  they  repeat  as  long  as  you 
hold  them  down.  Each  of  the  keyboard  areas  are 
explained  in  more  detail  below: 


Function  Keys 


Function 
Keys 


The  function  keys  can  be  used: 


•  As  "soft  keys."  That  is,  you  can  set  each  key  to 
automatically  type  any  sequence  of  characters. 
In  fact,  some  frequently-used  commands  have 
already  been  assigned  to  these  keys.  You  may 
change  these  if  you  wish.  Refer  to  "KEY 
Statement"  in  Chapter  4  for  details. 

•  As  program  interrupts  in  Advanced  BASIC, 
through  use  of  the  ON  KEY  statement.  See 
"ON  KEY(n)  Statement"  in  Chapter  4. 
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Typewriter  Keyboard 


Typewriter  Keyboard 

The  typewriter  area  of  the  keyboard  behaves  much 
like  a  standard  typewriter.  All  the  letters  are  there,  in 
their  usual  places.  The  numbers  0  through  9  are  on 
the  top  row,  along  with  some  special  characters. 


Capital  letters  and  the  special  characters  shown 
above  the  numbers  on  the  number  keys  are 
displayed  by  holding  down  either  of  the  Shift  keys 
and  pressing  the  desired  key. 

Note:  Although  the  supplied  keyboard  has  keytops 
corresponding  to  the  UK  layout,  Cassette  BASIC 
implements  the  US  layout  which  is  illustrated  at  the 
back  of  the  "Guide  to  Operations"  manual.  Refer  to 
the  DOS  section  of  "Guide  to  Operations"  for 
implementation  of  the  UK  layout  using  the  DOS 
diskette. 
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The  key  with  the  *J  symbol  on  it  is  the  carriage 
return  key.  You  usually  have  to  press  this  key  to 
enter  information  into  the  computer.  We  will  refer 
to  it  as  the  Enter  key  from  now  on. 

There  are  several  important  differences  between  this 
keyboard  and  a  regular  typewriter,  however. 


Special  Symbols: 


7,}   lnf-&  N 


1  T  T  T  If  VT 


This  keyboard  has  some  special  symbols  that  you 
won't  find  on  a  regular  typewriter,  like  "  ,  [,  and];  and 
some  characters  are  not  where  you  might  expect 
them  to  be  if  you're  used  to  using  a  typewriter.  For 
example,  the  uppershift  period  (.)  is  not  a  period, 
but  the  >  symbol. 
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Uppercase: 


This  keyboard  does  not  have  a  normal  Shift  Lock 
key.  The  Caps  Lock  key  is  similar  to  a  Shift  Lock  key, 
but  it  only  gives  you  capital  letters,  and  will  not  give 
you  the  uppershift  characters  on  the  numeric  or 
other  keys.  After  you  press  this  key,  you  will 
continue  to  get  capital  letters  until  you  press  it  again. 
You  can  get  lowercase  letters  when  in  Caps  Lock 
state  by  pressing  and  holding  one  of  the  Shift  keys. 
When  you  release  the  Shift  key,  you'll  go  back  to 
Caps  Lock  state. 


Backspace: 


The  Backspace  key  behaves  somewhat  differently 
from  the  Backspace  key  on  a  typewriter.  It  not  only 
backspaces,  it  erases  what  you've  typed  as  well.  You 
should  use  the  Cursor  Left  key  to  avoid  erasing  what 
you've  typed.  Refer  to  "The  BASIC  Program  Editor" 
later  in  this  chapter. 
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PrtSc: 


1  £&  v T>  r  V  r  t  t  t  r:  tar- 
: PttWYW\ 


l&f  "  f-  Ms  in 


t  i  nn  r'r  i  r 


Below  the  Enter  key  is  a  key  labeled  PrtSc  on  top  and 
*  on  the  bottom.  "PrtSc"  stands  for  "Print  screen." 
When  the  keyboard  is  in  lowershift,  pressing  this  key 
causes  an  asterisk  to  be  typed.  In  uppershift, 
however,  this  is  a  special  key  that  causes  a  copy  of 
what  is  on  the  screen  to  be  printed  on  the  printer 
(LPTl :).  So,  if  you  ever  need  a  hard  (printed)  copy  of 
what  is  currently  being  displayed,  just  press  and  hold 
one  of  the  Shift  keys,  and  press  the  PrtSc  key.  (Note: 
Characters  which  are  unrecognizable  by  the  printer 
are  printed  as  blanks.) 


Other  Shifts:  In  addition  to  the  Shift  keys  which 
change  the  keyboard  from  lowershift  to  uppershift, 
there  are  two  other  "shift"  keys  on  the  typewriter 
keyboard.  They  are  the  Alt  (Alternate)  and  the  Ctrl 
(Control)  keys.  You  use  both  of  these  keys  like  the 
Shift  keys;  that  is,  you  press  and  hold  the  Alt  (or  Ctrl) 
key,  then  press  the  desired  key.  Then  you  can  release 
both  keys.  However,  Alt  and  Ctrl  cause  different 
things  to  happen. 
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fVTVTTTTTTTTTTTTTTiT 


The  Alt  key  enables  easy  entry  of  BASIC  statement 
keywords.  This  key  allows  you  to  type  an  entire 
BASIC  keyword  with  a  single  keystroke. 


The  BASIC  keyword  is  typed  when  the  Alt  key  is  held 
down  while  one  of  the  alphabetic  keys  A-Z  is 
pressed.  Keywords  associated  with  each  letter  are 
summarized  below.  Letters  not  having  reserved 
words  are  noted  by  "(no  word)". 


A  AUTO 
B  BSAVE 
C  COLOR 
D  DELETE 
E  ELSE 
F  FOR 
G  GOTO 
H  HEX$ 
I  INPUT 
J     (no  word) 
K  KEY 
L  LOCATE 
M  MOTOR 


N  NEXT 
O  OPEN 
P  PRINT 
Q  (no  word) 
R  RUN 
S  SCREEN 
T  THEN 
U  USING 

V  VAL 

W  WIDTH 
X  XOR 

Y  (no  word) 
Z   (no  word) 


The  Alt  key  is  also  used  with  the  keys  on  the  numeric 
keypad  to  enter  characters  not  found  on  the  keys. 
This  is  done  by  holding  down  the  Alt  key  and  typing 
the  three-digit  ASCII  code  for  the  character.  (See 
"Appendix  G.  ASCII  Character  Codes"  for  a 
complete  list  of  ASCII  codes.) 
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mm 

i  ii  I  ri  nit 


The  Ctrl  key  is  also  used  to  enter  certain  codes  and 
characters  not  otherwise  available  from  the 
keyboard. 

For  example,  Ctrl-G  is  the  bell  character.  When  this 
character  is  printed,  the  speaker  beeps.  Note  how 
the  notation  "Ctrl-G"  means  you  press  and  hold  the 
Ctrl  key,  then  press  the  G  key.  Then  you  can  release 
both  keys. 


You  also  use  the  Ctrl  key  together  with  other  keys 
when  you  edit  programs  with  the  program  editor. 


Numeric  Keypad 


Numeric  Keypad 
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Usually  you  will  be  using  the  numeric  keypad  keys 
for  their  functions  with  the  program  editor.  These 
keys  allow  you  to  move  the  cursor  up,  down,  right, 
and  left.  You  can  insert  and  delete  characters  using 
these  keys.  Refer  to  the  following  section,  "The 
BASIC  Program  Editor,"  for  complete  information. 

Note:  The  Scroll  Lock,  Pg  Up,  and  Pg  Dn  keys 
are  not  used  by  BASIC,  but  they  may  be  given 
meaning  within  a  program. 


Keypad  Shift:  You  can  use  the  Num  Lock  key  to  set 
the  numeric  keypad  so  it  works  more  like  a 
calculator  keypad.  Pressing  the  Num  Lock  key  shifts 
the  numeric  keypad  into  its  own  uppershift  mode,  so 
that  you  get  the  numbers  0  through  9  and  the 
decimal  point,  as  indicated  on  the  keytops.  Pressing 
Num  Lock  again  will  return  the  keypad  to  its  normal 
cursor  control  mode.  As  with  Caps  Lock,  you  can 
temporarily  reverse  the  Num  Lock  state  by  pressing 
one  of  the  Shift  Keys. 


Special  Key  Combinations 


You  should  be  aware  of  the  special  functions  of  the 
following  combinations  of  keys: 


Ctrl-Break 


jLotk  i 
Break 


r-T.n  r  1 rn  i 1*1/4. 

 1  1 


Ctrl-Break  interrupts  program 
execution  at  the  next  BASIC 
instruction  and  returns  to  BASIC 
command  level.  It  is  also  used  to 
exit  AUTO  line  numbering  mode. 


Ctrl-Num  Lock  sends  the 
computer  into  a  pause  state.  This 
can  be  used  to  temporarily  halt 
printing  or  program  listing.  The 
pause  continues  until  any  key 
other  than  the  "shift"  keys,  the 
Break  key,  and  the  Ins  key,  is 
pressed.  (See  "Uppercase," 
"Other  Shifts,"  and  "Keypad 
Shift"  earlier  in  this  section.) 
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Alt-Ctrl-Del 


If  the  computer  power  is  on, 
Alt-Ctrl-Del  performs  a  System 
Reset,  In  other  words,  it's  similar  to 
switching  the  computer  from  off 
to  on.  You  must  press  the  Ctrl  and 
Alt  keys  (in  either  order)  and  hold 
them  down,  then  press  the  Del 
key.  Then  you  can  release  all  three 
keys.  Doing  a  System  Reset  with 
these  keys  is  preferable  to  flipping 
the  power  switch  off  and  on  again, 
because  the  system  will  start 
faster. 
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The  BASIC  Program  Editor 

Any  line  of  text  typed  while  BASIC  is  at  command 
level  is  processed  by  the  BASIC  program  editor.  The 
program  editor  is  a  "screen  line  editor."  That  is,  you 
can  change  a  line  anywhere  on  the  screen,  but  you 
can  only  change  one  line  at  a  time.  The  change  will 
only  take  effect  if  you  press  Enter  on  that  line. 

Use  of  the  program  editor  can  save  a  lot  of  time 
during  program  development.  To  become  familiar 
with  its  features,  we  suggest  you  enter  a  sample 
program  and  practice  all  the  editing  capabilities.  The 
best  way  for  you  to  get  a  "feel"  for  the  editing 
process  is  to  try  editing  a  few  lines  while  studying  the 
information  that  follows. 

As  you  type  things  on  your  computer,  you'll  notice  a 
blinking  underline  or  box  appearing  just  to  the  right 
of  the  last  character  you  typed.  This  line  or  box  is 
called  the  cursor.  It  marks  the  next  position  at  which  a 
character  is  to  be  typed,  inserted,  or  deleted. 

Special  Program  Editor  Keys 

You  use  the  keys  on  the  numeric  keypad,  the 
Backspace  key,  and  the  Ctrl  key  to  move  the  cursor 
to  a  location  on  the  screen,  insert  characters,  or 
delete  characters.  The  keys  and  their  functions  are 
listed  on  the  next  pages. 
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Key(s) 


Function 


Home 


Homei 


'-^TLH^T:T-  T -ITT.- 

f  v  twin  u 


■  rrmTT  i  r 


+".1- 


Moves  the  cursor  to  the  upper  left-hand 
corner  of  the  screen. 


Ctrl-Home 


Cnl 


7  \ 

Hoinei  I 

111 


V  V  T  T  T  T  T  T  T  J-  T  Tr^T'n 


Clears  the  screen  and  positions  the  cursor 
in  the  upper  left-hand  corner  of  the  screen. 
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Key(s) 

Function 

t 

(Cursor  Up) 

F") 

(r  > 

M 

",","11 

/-  ■ 
!«' 

1,sJ 

H 
in? 

/■  j* 

ov 

I 

'5  T  T  T t  T.tVt  iV  Vi 

es  the  cursor  one  position  up 

, 

r  « 

i 

(Cursor  Down) 

IP 

• 

M 

J 

r,vf 

H 

t  -\ 

H 
ov 

es  the  cursor  one  position  do 

(O 

T-  1  'I 

■  i>,  >  r  * 

1  fl  If 

wn. 
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Key(s) 


(Cursor  Left) 


Function 


Mi 


^UTTM.nii!.! 

niinr:: 


f3 


Moves  the  cursor  one  position  left.  If  the 
cursor  advances  beyond  the  left  edge  of  the 
screen,  the  cursor  will  move  to  the  right 
side  of  the  screen  on  the  preceding  line. 


(Cursor  Right) 


r  T  I  T  I  T  III  I  II  " 


Moves  the  cursor  one  position  right.  If  the 
cursor  advances  beyond  the  right  edge  of 
the  screen,  the  cursor  will  move  to  the  left 
side  of  the  screen  on  the  next  line  down. 
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Key(s) 


Function 


Ctrl- 


(Next  Word) 


Moves  the  cursor  right  to  the  next  word.  A 
word  is  defined  as  a  character  or  group  of 
characters  which  begins  with  a  letter  or 
number.  Words  are  separated  by  blanks  or 
special  characters.  So,  the  next  word  will 
be  the  next  letter  or  number  to  the  right  of 
the  cursor  which  follows  a  blank  or  special 
character. 

For  example,  suppose  we  have  the 
following  line: 


As  you  can  see,  the  cursor  is  presently  in 
the  middle  of  the  word  LOW2.  If  we  press 
Next  Word  (Ctrl-Cursor  Right),  the  cursor 
will  move  to  the  beginning  of  the  next 
word,  which  is  MAX: 


If  we  press  Next  Word  again,  the  cursor 
will  move  to  the  next  word,  which  is  the 
number  48: 
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Key(s) 
Ctrl- 

(Previous  Word) 


Function 


Moves  the  cursor  left  to  the  previous  word. 
The  previous  word  will  be  the  letter  or 
number  to  the  left  of  the  cursor  which  is 
preceded  by  a  blank  or  special  character. 

For  example,  suppose  we  have: 

LINE    (LI ,L0W2) - (MAX, ^8)    ,3    ,  BF_ 

If  we  press  Previous  Word  (Ctrl-Cursor 
Left),  the  cursor  moves  to  the  beginning 
of  the  word  BF: 

LINE    (LI  ,  L0W2) - (MAX, ^8)    ,3    ,  BF 

When  we  press  Previous  Word  again,  the 
cursor  moves  to  the  previous  word,  which 
is  the  number  3: 

LINE   {L1 ,LGW2)-(MAX,^8j    ,J  ,  BF 

And  if  we  press  it  twice  more,  the  cursor 
will  back  up  first  to  the  number  48,  then  to 
the  word  MAX: 

LINE   (LI  tL0W2)-(MAX>8)    ,3   ,  BF 


Function 


End 


rr  r  vvv  ft  T-n-rj 
:  t_i  i  r  i  t  m  i  m_t  -  : 


ft? 1  "t  "t1. 

(4'  j  II 


Moves  the  cursor  to  the  end  of  the  logical 
line.  Characters  typed  from  this  position 
are  added  to  the  end  of  the  line. 


Ctrl-End 


F  ml 


v  n;  r  Till t  r 

i  t  t  rrn  t-t- 


Erases  to  the  end  of  logical  line  from  the 
current  cursor  position.  All  physical  screen 
lines  are  erased  until  the  terminating  Enter 
is  found. 
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Key(s) 


Function 


Ins 


m 

Sets  insert  mode.  If  insert  mode  is  off,  then 
pressing  this  key  will  turn  it  on.  If  insert 
mode  is  already  on,  then  you  will  turn  it  off 
when  you  press  this  key.  When  you're  in 
insert  mode,  the  cursor  covers  the  lower 
half  of  the  character  position. 

When  insert  mode  is  on,  characters  above 
and  following  the  cursor  move  to  the  right 
as  typed  characters  are  inserted  at  the 
current  cursor  position.  After  each 
keystroke,  the  cursor  moves  one  position 
to  the  right.  Line  folding  occurs;  that  is,  as 
characters  advance  off  the  right  side  of  the 
screen  they  return  on  the  left  on  a 
subsequent  line. 

When  insert  mode  is  off,  any  characters 
typed  replace  existing  characters  on  the 
line. 

Besides  pressing  the  Ins  key  again,  insert 
mode  will  also  be  turned  off  when  you 
press  any  of  the  cursor  movement  keys  or 
the  Enter  key. 


;TI  I  I  I  T  III  1  1 


r  T  r_r_  "rT - 
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Kcy(s) 

Function 

Del 

rthl  f-  T.  Tf  Ti  Y:  is  T?  !P  Y:  I;  Y;  Y  r:  T*-  'y^Tf^srt 

a !-f  Mr  r  r  r  r  "T-  r  r  r  f  Y{  r!' jr?  BP '  £f  " 
P  w  r  t  T  T  T  Is  T  I  T  T  l  T  I  ' :  ' ,f  ■  f ;  r1 

j  p^i  r  r  r  r  r  r  t  t  y^i^pj 

Deletes  the  character  at  the  current  cursor 
position.  All  characters  to  the  right  of  the 
deleted  character  move  one  position  left  to 
fill  in  the  empty  space.  Line  folding  occurs; 
that  is,  if  a  logical  line  extends  beyond  one 
physical  line,  characters  on  subsequent 
lines  move  left  one  position  to  fill  in  the 
previous  space,  and  the  character  in  the 
first  column  of  each  subsequent  line  moves 
up  to  the  end  of  the  preceding  line. 
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Key(s) 


Function 


(Backspace) 


mmmm 


Deletes  the  last  character  typed.  That  is,  it 
deletes  the  character  to  the  left  of  the 
cursor.  All  characters  to  the  right  of  the 
deleted  character  move  left  one  position  to 
fill  in  the  space.  Subsequent  characters  and 
lines  within  the  current  logical  line  move 
up  as  with  the  Del  key. 


When  pressed  anywhere  in  the  line,  erases 
the  entire  logical  line  from  the  screen.  The 
line  is  not  passed  to  BASIC  for  processing. 
If  it  is  a  program  line,  it  is  not  erased  from 
the  program  in  memory. 
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Key(s) 


Function 


Ctrl- Break 


i  ILock 


0  !■ 


-  ri'i  i  i  i  r  i  r  i  it  ■ 

r  4  r  ^ 


Returns  to  command  level,  without  saving 
any  changes  that  were  made  to  the  current 
line  being  edited.  It  does  not  erase  the  line 
from  the  screen  like  Esc  does. 
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Key(s) 

Function 

(Tab) 

■    '  u  1 1 1  t  1 i 1  n j  •  f '  t 

Moves  the  cursor  to  the  next  tab  stop.  Tab 
stops  occur  every  eight  character 
positions;  that  is,  at  positions  1,9,  17,  etc. 

When  insert  mode  is  off,  pressing  the  Tab 
key  moves  the  cursor  over  characters  until 
it  reaches  the  next  tab  stop. 

For  example,  suppose  we  have  the 
following  line: 

If  we  press  the  Tab  key,  the  cursor  will 
move  to  the  ninth  position  as  shown: 

If  we  press  the  Tab  key  again,  the  cursor 
moves  to  the  17th  position  on  the  line: 
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Key(s) 

Function 

(Tab) 

(continued) 

When  insert  mode  is  on,  pressing  the  Tab 
key  inserts  blanks  from  the  current  cursor 
position  to  the  next  tab  stop.  Line  folding 
occurs  as  explained  under  Ins. 

For  example,  suppose  we  have  this  line: 

If  we  press  the  Ins  key  and  then  the  Tab 
key,  blanks  are  inserted  up  to  position  17: 
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How  to  Make  Corrections  on  the  Current 
Line 


Since  any  line  of  text  typed  while  BASIC  is  at 
command  level  is  processed  by  the  program  editor, 
you  can  use  any  of  the  keys  described  in  the  previous 
section  under  "Special  Program  Editor  Keys." 
BASIC  is  always  at  command  level  after  the  prompt 
Ok  and  until  a  RUN  command  is  given. 

A  logical  line  is  a  string  of  text  which  BASIC  treats  as  a 
unit.  It  is  possible  to  extend  a  logical  line  over  more 
than  one  physical  screen  line  by  simply  typing 
beyond  the  edge  of  the  screen.  The  cursor  will  wrap 
to  the  next  screen  line.  You  can  also  use  a  line  feed 
(Ctrl-Enter).  Typing  a  line  feed  causes  subsequent 
text  to  be  printed  on  the  next  screen  line  without 
your  having  to  enter  all  the  blanks  to  move  the 
cursor  there.  The  line  is  not  processed;  this  only 
happens  when  you  press  Enter. 

Note  that  the  line  feed  actually  causes  the  remainder 
of  the  physical  screen  line  to  be  filled  with  blank 
characters.  A  line  feed  character  is  not  added  to  the 
text.  These  blanks  are  included  in  the  255  characters 
allowed  for  a  BASIC  line. 

When  the  Enter  key  is  finally  pressed,  the  entire 
logical  line  is  passed  to  BASIC  for  processing. 

Changing  Characters:    If  you  are  typing  a  line  and 
discover  you  typed  something  incorrectly,  you  can 
correct  it.  Use  the  Cursor  Left  or  other  cursor 
movement  keys  to  move  the  cursor  to  the  position 
where  the  mistake  occurred,  and  type  the  correct 
letters  on  top  of  the  wrong  ones.  Then  you  can  move 
the  cursor  back  to  the  end  of  the  line  using  the 
Cursor  Right  or  End  keys,  and  continue  typing. 


2-32 


For  example,  suppose  we  have  typed  the  following: 


We  accidently  typed  V;  instead  of  B:.  We  fix  the 
problem  by  pressing  Previous  Word  (Ctrl-Cursor 
Left)  twice,  until  the  cursor  is  under  the  V: 


The  error  is  fixed  and  we  can  continue  typing: 

0-D  "B  :  PROGRAM  i  " 


Erasing  Characters:  If  you  notice  you've  typed  an 
extra  character  in  the  line  you're  typing,  you  can 
erase  (delete)  it  using  the  Del  key.  Use  the  Cursor 
Left  or  other  cursor  movement  keys  to  move  the 
cursor  to  the  character  you  want  to  erase.  Press  the 
Del  key,  and  it  is  deleted.  Then  use  the  Cursor  Right 
or  End  keys  to  move  the  cursor  back  to  the  end  of  the 
line,  and  continue  typing. 

For  example,  suppose  we  typed  the  following: 

To  erase  the  extra  E,  we  press  Cursor  Left  until  the 
cursor  is  under  the  extra  E: 


Then  we  press  the  End  key: 


Then  we  type  B:: 


0AD"B : PRC 


'B  :PP0G 


r 
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Then  we  press  the  Del  key: 


Then  we  press  the  End  key: 


and  continue  typing: 


If  the  incorrect  character  was  the  character  you  just 
typed,  use  the  Backspace  key  to  delete  it.  Then  you 
can  simply  continue  typing  the  line  as  desired. 

For  example,  suppose  we've  typed  the  following: 


We  can  simply  press  the  Backspace  key: 


Then  we  can  continue  typing: 


Adding  Characters:  If  you  see  that  you've  omitted 
characters  in  the  line  you're  typing,  move  the  cursor 
to  the  position  where  you  want  to  put  the  new 
characters.  Press  the  Ins  key  to  get  into  Insert  Mode. 
Type  the  characters  you  want  to  add.  The  characters 
you  type  will  be  inserted  at  the  cursor  and  the 
characters  above  and  following  it  will  be  pushed  to 
the  right.  As  before,  when  you're  ready  to  continue 
typing  at  the  end  of  the  line,  use  the  Cursor  Right  or 
End  keys  to  move  the  cursor  there  and  just  continue 
typing.  Insert  Mode  will  automatically  be  turned  off 
when  you  use  either  ol  these  keys. 
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For  example,  suppose  we've  typed  the  following: 


We  forgot  the  T  in  LIST.  So  we  press  Cursor  Left 
until  the  cursor  is  under  the  space: 


Then  we  press  the  Ins  key  and  type  the  letter  T: 


Erasing  Part  of  a  Line:  To  truncate  a  line  at  the 
current  cursor  position,  press  Ctrl-End. 

For  example,  suppose  we  have  the  following: 


We  have  the  cursor  positioned  under  the  g  in  the 
first  word  garbage,  so  all  we  have  to  do  to  erase  the 
garbage  is  press  Ctrl-End: 


Cancelling  a  Line:    To  cancel  a  line  that  is  in  the 
process  of  being  typed,  press  the  Esc  key  anywhere 
in  the  line.  You  do  not  have  to  press  Enter.  This 
causes  the  entire  logical  line  to  be  erased. 

For  example,  suppose  we  had  this  line: 


Even  though  the  cursor  is  at  the  end  of  the  line,  the 
entire  line  is  erased  when  we  press  Esc: 
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Entering  or  Changing  a  BASIC  Program 


Any  line  of  text  that  you  type  that  begins  with  a 
number  is  considered  to  be  a  program  line. 

A  BASIC  program  line  always  begins  with  a  line 
number,  ends  with  an  Enter,  and  may  contain  a 
maximum  of  25  5  characters,  including  the  Enter.  If  a 
line  contains  more  than  25  5  characters,  the  extra 
characters  will  be  truncated  when  the  Enter  is 
pressed.  Even  though  the  extra  characters  still 
appear  on  the  screen,  they  are  not  processed  bv 
BASIC. 

BASIC  keywords  and  variable  names  must  be  in 
uppercase.  However,  you  may  enter  them  in  any 
combination  of  uppercase  and  lowercase.  The 
program  editor  will  convert  everything  to 
uppercase,  except  for  remarks,  DATA  statements, 
and  strings  enclosed  in  quotation  marks. 

BASIC  will  sometimes  change  the  way  you  enter 
something  in  other  ways.  For  example,  suppose  you 
use  the  question  mark  (?)  instead  of  the  word  PRINT 
in  a  program  line.  When  you  later  LIST  the  line,  the  ? 
will  be  changed  to  PRINT  with  a  space  after  it, 
since  ?  is  a  shorthand  way  of  entering  PRINT.  This 
expansion  may  cause  the  end  of  a  line  to  be 
truncated  if  the  line  length  is  close  to  2  5  5  characters. 

Warning: 

If  your  line  reaches  maximum  length,  the  255  th 
character  must  be  Enter. 

Adding  a  New  Line  to  the  Program:  Enter  a  valid 
line  number  (range  is  0  through  65  5  29)  followed  by 
at  least  one  non-blank  character,  followed  by  Enter. 
The  line  will  be  saved  as  part  of  the  BASIC  program 
in  storage. 
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For  example,  if  you  enter  the  following: 


This  will  save  the  line  as  line  number  10  in  the 
program.  Note  that  hello  Dori  is  not  a  valid  BASIC 
statement;  however,  you  will  not  get  an  error  if  you 
enter  this  line.  Program  lines  are  not  checked  for 
proper  syntax  before  being  added  to  the  program. 
That  only  happens  when  the  program  line  is  actually 
executed. 

If  a  line  already  exists  with  the  same  line  number, 
then  the  old  line  is  erased  and  replaced  with  the  new 
one. 

If  you  try  to  add  a  line  to  a  program  when  there  is  no 
more  room  in  storage,  an  "Out  of  memory"  error 
occurs  and  the  line  is  not  added. 


Replacing  or  Changing  an  Existing  Program  Line: 

An  existing  line  is  changed,  as  indicated  above,  when 
the  line  number  of  the  line  you  enter  matches  the 
line  number  of  a  line  already  in  the  program.  The  old 
line  is  replaced  with  the  text  of  the  new  one. 

For  example,  if  you  enter: 


The  previous  line  10  (  hello  Dori  )  would  be 
replaced  with  this  new  line  10. 


Deleting  Program  Lines:    To  delete  an  existing 
program  line,  type  the  line  number  alone  followed 
by  Enter.  For  example,  if  you  enter: 


This  would  delete  line  10  from  the  program. 
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Or  you  may  use  the  DELETE  command  to  delete  a 
group  of  program  lines.  Refer  to  "DELETE 
Command"  in  Chapter  4  for  details. 

Note  that  if  you  try  to  delete  a  non-existent  line,  an 
"Undefined  line  number"  error  will  occur. 

Do  not  use  the  Esc  key  to  delete  program  lines.  Esc 
will  cause  the  line  to  be  erased  from  the  screen  only. 
If  the  line  exists  in  the  BASIC  program,  it  will  remain 
there. 


Deleting  an  Entire  Program:    To  delete  the  entire 
program  that  is  currently  residing  in  memory,  enter 
the  NEW  command  (see  "NEW  Command'1  in 
Chapter  4).  NEW  is  usually  used  to  clear  memory 
prior  to  entering  a  new  program. 

Changing  Lines  Anywhere  on  the  Screen 

You  can  edit  any  line  on  the  screen  simply  by  using 
the  cursor  movement  keys  (described  under 
"Special  Program  Editor  Keys")  to  move  the  cursor 
on  the  screen  to  the  place  requiring  the  change. 
Then  you  can  use  any  or  all  of  the  techniques 
described  previously  to  change,  delete,  or  add 
characters  to  the  line. 

If  you  want  to  modify  program  lines  that  do  not 
happen  to  be  displayed  at  the  moment,  you  can  use 
the  LIST  command  to  display  them.  List  the  line  or 
range  of  lines  to  be  edited  (see  "LIST  Command"  in 
Chapter  4).  Position  the  cursor  to  a  line  to  be  edited 
and  change  the  line  using  the  techniques  already 
described.  Press  Enter  to  store  the  modified  line  in 
the  program.  You  can  also  use  the  EDIT  command 
to  display  the  line  you  want.  Refer  to  "EDIT 
Command"  in  Chapter  4. 
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For  example,  you  could  duplicate  a  line  in  the 
program  this  way:  Move  the  cursor  to  the  line  to  be 
duplicated.  Change  the  line  number  to  the  new  line 
number  by  just  typing  over  the  numbers.  When  you 
press  Enter,  both  the  old  line  and  the  new  line  will  be 
in  the  program. 

Or,  you  could  change  the  line  number  of  a  program 
line  by  duplicating  the  line  as  described  above,  then 
deleting  the  old  line. 

A  program  line  is  never  actually  changed  within  the 
BASIC  program  until  Enter  is  pressed.  Therefore, 
when  several  lines  need  alteration,  it  may  be  easier  to 
move  around  the  screen  making  corrections  to 
several  lines  at  once,  and  then  go  back  to  the  first  line 
changed  and  press  Enter  at  the  beginning  of  each 
line.  By  so  doing,  you  store  each  modified  line  in  the 
program. 

You  do  not  have  to  move  the  cursor  to  the  end  of  the 
logical  line  before  pressing  Enter.  The  program 
editor  knows  where  each  logical  line  ends  and  it 
processes  the  whole  line  even  if  the  Enter  is  pressed 
at  the  beginning  of  the  line. 

Note:    Use  of  the  AUTO  command  can  be  very 
helpful  when  you  are  entering  your  program. 
However,  you  should  exit  AUTO  mode  by 
pressing  Ctrl-Break  before  changing  any  lines 
other  than  the  current  one. 

Remember,  changes  made  using  these  techniques 
only  change  the  program  in  memory.  To  save  the 
program  with  the  new  changes  permanently,  you 
should  use  the  SAVE  command  (see  "SAVE 
Command"  in  Chapter  4)  before  entering  a  NEW 
command  or  leaving  BASIC. 
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Syntax  Errors 

When  a  syntax  error  is  discovered  while  a  program  is 
running,  BASIC  automatically  displays  the  line  that 
caused  the  error  so  you  may  correct  it.  For  example: 


The  program  editor  has  displayed  the  line  in  error 
and  positioned  the  cursor  right  under  the  digit  1. 
You  can  move  the  cursor  right  to  the  dollar  sign  ($) 
and  change  it  to  a  plus  sign  (+),  then  press  Enter.  The 
corrected  line  is  now  stored  back  in  the  program. 

When  you  edit  a  line  and  store  it  back  in  the  program 
while  the  program  is  interrupted  (as  in  this  example) 
certain  things  happen,  primarily: 

•  All  variables  and  arrays  are  lost.  That  is,  they  are 
reset  to  zero  or  null. 

•  Any  files  that  were  open  are  closed. 

•  You  cannot  use  CONT  to  continue  the 
program. 

If  you  want  to  examine  the  contents  of  some  variable 
before  making  the  change,  you  should  press 
Ctrl-Break  to  return  to  command  level.  The 
variables  will  be  preserved  since  no  program  line  is 
changed.  After  you  check  everything  you  need  to, 
you  can  edit  the  line  and  rerun  the  program. 
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Line  Format 


Program  lines  in  a  BASIC  program  have  the 
following  format: 

nnnnn  BASIC  statement[:BASIC  statement...]!'  comment  ] 

and  they  end  with  Enter.  This  format  is  explained  in 
more  detail  below. 


Line  Numbers:    "nnnnn"  indicates  the  line 
number,  which  can  be  from  one  to  five  digits.  Every 
BASIC  program  line  begins  with  a  line  number.  Line 
numbers  are  used  to  show  the  order  in  which  the 
program  lines  are  stored  in  memory  and  also  as 
reference  points  for  branching  and  editing.  Line 
numbers  must  be  in  the  range  0  to  65  5  29-  A  period 
(.)  may  be  used  in  LIST,  AUTO,  DELETE,  and  EDIT 
commands  to  refer  to  the  current  line. 


BASIC  Statements:    A  BASIC  statement  is  either 
executable  ox  non-executable.  Executable  statements  are 
program  instructions  that  tell  BASIC  what  to  do 
next  while  running  a  program.  For  example,  PRINT 
X  is  an  executable  statement.  Non-executable 
statements,  such  as  DATA  or  'REM,  do  not  cause  any 
program  action  when  BASIC  sees  them.  All  the 
BASIC  statements  are  explained  in  detail  in  the  nexi 
chapter. 
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You  may,  if  you  wish,  have  more  than  one  BASIC 
statement  on  a  line,  but  each  statement  on  a  line 
must  be  separated  from  the  last  one  by  a  colon,  and 
the  total  number  of  characters  must  not  exceed  255- 

For  example: 

10    -"OR    !-i    ro  5:    PRINT    I  :  NEXT 

L>  i  if- 


O  k 


Comments:  Comments  may  be  added  to  the  end 
of  a  line  using  the  '  (single  quote)  to  separate  the 
comment  from  the  rest  of  the  line. 


Character  Set 


The  BASIC  character  set  consists  of  alphabetic 
characters,  numeric  characters  and  special 
characters.  These  are  the  characters  which  BASIC 
recognizes. 

The  alphabetic  characters  in  BASIC  are  the 
uppercase  and  lowercase  letters  of  the  alphabet.  The 
numeric  characters  are  the  digits  0  through  9- 
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The  following  special  characters  have  specific 
meanings  in  BASIC: 


Character  Name 
blank 

=         equal  sign  or  assignment  symbol 
+         plus  sign  or  concatenation  symbol 
minus  sign 

*  asterisk  or  multiplication  symbol 
/         slash  or  division  symbol 

\  backslash  or  integer  division  symbol 

caret  or  exponentiation  symbol 
(  left  parenthesis 

)  right  parenthesis 

%         percent  sign  or  integer  type  declaration 
character 

#  number  (or  pound)  sign,  or 
double-precision  type  declaration 
character 

$  dollar  sign  or  string  type  declaration 

character 

!  exclamation  point  or  single-precision 

type  declaration  character 
&  ampersand 
,  comma 

period  or  decimal  point 

single  quotation  mark  (apostrophe),  or 

remark  delimiter 
;  semicolon 

:  colon  or  statement  separator 

?  question  mark  (PRINT  abbreviation) 

<         less  than 

>         greater  than 

double  quotation  mark  or  string 

delimiter 

underline 


Many  characters  can  be  printed  or  displayed  even 
though  they  have  no  particular  meaning  to  BASIC, 
See  "Appendix  G.  ASCII  Character  Codes"  for  a 
complete  list  of  these  characters. 
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served  Words 


Certain  words  have  special  meaning  to  BASIC.  These 
words  are  called  reserved  words.  Reserved  words 
include  all  BASIC  commands,  statements,  function 
names,  and  operator  names.  Reserved  words  cannot 
be  used  as  variable  names. 

You  should  always  separate  reserved  words  from 
data  or  other  parts  of  a  BASIC  statement  by  using 
spaces  or  other  special  characters  as  allowed  by  the 
syntax.  That  is,  the  reserved  words  must  be 
appropriately  delimited  so  that  BASIC  will  recognize 
them. 

The  following  is  a  list  of  all  the  reserved  words  in 


BASIC. 

ABS 

CVD 

AND 

CVI 

ASC 

CVS 

ATN 

DATA 

AUTO 

DATE  £ 

BEEP 

DEF 

BLOAD 

DEFDBL 

8  SAVE 

DEF 1  NT 

CALL 

DEFSNG 

CDBL 

DEFSTR 

CHAI  N 

DELETE 

CHR$ 

DIM 

CINT 

DRAW 

CIRCLE 

EDIT 

CLEAR 

ELSE 

CLOSE 

END 

CLS 

EOF 

COLOR 

EQV 

COM 

ERASE 

COMMON 

ERL 

CONT 

ERR 

COS 

ERROR 

CSNG 

EXP 

CSRLI N 

Fl  ELD 

FILES 
FIX 

FNxxxxxxxx 

FOR 

FRE 

GET 

GOSUB 

GOTO 

HEX$ 

I  F 

I  MP 

I  NKEY$ 
I  NP 
I  NPUT 
I  NPUT# 
I NPUT$ 
I  NSTR 
I  NT 
KEY 
Kl  LL 
LEFT$ 
LEN 
LET 
L  I  NE 
L  1ST 
LL  I  ST 
LOAD 
LOC 

LOCATE 

LOF 

LOG 

LPOS 

LPRI NT 

LSET 

MERGE 

M  1  D$ 

MKD$ 

MK1  $ 

MKS$ 

MOD 

MOTOR 

NAME 

NEW 

NEXT 


NOT 
OCT$ 
OFF 
ON 

OPEN 

OPT  I  ON 

OR 

OUT 

PAI  NT 

PEEK 

PEN 

PLAY 

POI  NT 

POKE 

POS 

PRESET 
PRINT 
PR  I  NT-* 
PSET 
PUT 

RANDOM  I ZE 

READ 

REM 

RENUM 

RESET 

RESTORE 

RESUME 

RETURN 

R I GHT$ 

RND 

RSET 

RUN 

SAVE 

SCREEN 

SGN 

S  1  N 

SOUND 

SPACE$ 

SPC  ( 

SQR 

STEP 

STICK 

STOP 

STR$ 
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STRIG 

USR 

STRI NG  $ 

VAL 

SWAP 

VARPTR 

SYSTEM 

VARPTR$ 

TAB  ( 

WAIT 

TAN 

WEND 

THEN 

WHI  LE 

T  1  ME  $ 

W  1  DTH 

TO 

WRITE 

TROFF 

WR 1 TE# 

IRON 

XOR 

US  1  NG 

Constants 


Constants  are  the  actual  values  BASIC  uses  during 
execution.  There  are  two  types  of  constants:  string 
(or  character)  constants,  and  numeric  constants. 

A  string  constant  is  a  sequence  of  up  to  255 
characters  enclosed  in  double  quotation  marks. 
Examples  of  string  constants: 

"HELLO1 
"S75.000 .00" 


Numeric  constants  are  positive  or  negative 
numbers.  A  plus  sign  (+)  is  optional  on  a  positive 
number.  Numeric  constants  in  BASIC  cannot 
contain  commas.  There  are  five  ways  to  indicate 
numeric  constants: 

Integer  Whole  numbers  between  -32768 

and  +32767,  inclusive.  Integer 
constants  do  not  have  decimal 
points. 

Fixed  point  Positive  or  negative  real 

numbers,  that  is,  numbers  that 
contain  decimal  points. 

Floating  point     Positive  or  negative  numbers 

represented  in  exponential  form 
(similar  to  scientific  notation).  A 
floating  point  constant  consists 
of  an  optionally  signed  integer  or 
fixed  point  number  (the 
mantissa)  followed  by  the  letter  E 
and  an  optionally  signed  integer 
(the  exponent).  Double-precision 
floating  point  constants  use  the 
letter  D  instead  of  E.  For  more 
information,  see  the  next 
section,  "Numeric  Precision." 
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The  E  (or  D)  means  "times  ten  to 
the  power  of." 

For  example, 

?  3  E  -  2 

Here,  23  is  the  mantissa,  and  -2  is 
the  exponent.  This  number 
could  be  read  as  "twenty- three 
times  ten  to  the  negative  two 
power."  You  could  write  it  as 
0.23  in  regular  fixed  point 
notation.  More  examples: 

?  5  .  ?  3  8  i  -  / 
is  equivalent  to:  .0000235988 


is  equivalent  to:  2359000000 

You  can  represent  any  number 
from  2.9E-39  to  1.7E+38 
(positive  or  negative)  as  a  floating 
point  constant. 

Hexadecimal  numbers  with  up  to 
four  digits,  with  a  prefix  of  &H. 
Hexadecimal  digits  are  the 
numbers  0  through  9,  A,  B,  C,  D, 
E,  and  F.  Examples: 


Octal  numbers  with  up  to  6 
digits,  with  the  prefix  &O  or  just 
&.  Octal  digits  are  0  through  7 
Examples: 


Numeric  Precision 


Numbers  may  be  stored  internally  as  either  integer, 
single-precision,  or  double-precision  numbers. 
Constants  entered  in  integer,  hex,  or  octal  format 
are  stored  in  two  bytes  of  memory  and  are 
interpreted  as  integers  or  whole  numbers.  With 
double-precision,  the  numbers  are  stored  with  17 
digits  of  precision  and  printed  with  up  to  16  digits. 
With  single-precision,  seven  digits  are  stored  and  up 
to  seven  digits  are  printed,  although  only  six  digits 
will  be  accurate. 

A  single-precision  constant  is  any  numeric  constant 
that  doesn't  fit  in  the  integer  category  and  is  written 
with: 

•  seven  or  fewer  digits,  or 

•  exponential  form  using  E,  or 

•  a  trailing  exclamation  point  (!) 

A  double-precision  constant  is  any  numeric  constant 
that  is  written  with: 

•  eight  or  more  digits,  or 

•  exponential  form  using  D,  or 

•  a  trailing  number  sign  (#) 

Examples  of  single-  and  double-precision  constants: 


Single- Precision 
46.8 

-1.09E-06 
3489.0 
22.5! 


Double- Precision 

345692811 
-1.09432D-06 
3489.0# 
7654321.1234 
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Variables 


Variables  are  names  used  to  represent  values  that  are 
used  in  a  BASIC  program.  As  with  constants,  there 
are  two  types  of  variables:  numeric  and  string.  A 
numeric  variable  always  has  a  value  that  is  a  number. 
A  string  variable  may  only  have  a  character  string 
value. 

The  length  of  a  string  variable  is  not  fixed,  but  may 
be  anywhere  from  0  (zero)  to  255  characters.  The 
length  of  the  string  value  you  assign  to  it  will 
determine  the  length  of  the  variable. 

You  may  set  the  value  of  a  variable  to  a  constant,  or 
you  can  set  its  value  as  the  result  of  calculations  or 
various  data  input  statements  in  the  program.  In 
either  case,  the  variable  type  (string  or  numeric) 
must  match  the  type  of  data  that  is  being  assigned  to 
it. 

If  you  use  a  numeric  variable  before  you  assign  a 
value  to  it,  its  value  is  assumed  to  be  zero.  String 
variables  are  initially  assumed  to  be  null;  that  is,  they 
have  no  characters  in  them  and  have  a  length  of  zero. 

How  to  Name  a  Variable 

BASIC  variable  names  may  be  any  length.  If  the 
name  is  longer  than  40  characters,  however,  only  the 
first  40  characters  are  significant. 

The  characters  allowed  in  a  variable  name  are  letters 
and  numbers,  and  the  decimal  point.  The  first 
character  must  be  a  letter.  Special  characters  which 
identify  the  type  of  variable  are  also  allowed  as  the 
last  character  of  the  name.  For  more  information 
about  types,  see  the  next  section,  "How  to  Declare 
Variable  Types." 
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A  variable  name  may  not  be  a  reserved  word,  but 
may  contain  imbedded  reserved  words.  (Refer  to 
"Reserved  Words,"  earlier  in  this  chapter,  for  a 
complete  list  of  the  reserved  words.)  Also,  a  variable 
name  may  not  be  a  reserved  word  with  one  of  the 
type  declaration  characters  ($,  %, !,  #)  at  the  end.  For 
example, 

10  EXP  =  5 

is  invalid,  because  EXP  is  a  reserved  word.  However, 

1,0  EXPONENT  =  5 

is  okay,  because  EXP  is  only  a  part  of  the  variable 
name. 

A  variable  beginning  with  FN  is  assumed  to  be  a  call 
to  a  user-defined  function(see  "DEF  FN  Statement" 
in  Chapter  4). 


How  to  Declare  Variable  Types 

A  variable's  name  determines  its  type  (string  or 
numeric,  and  if  numeric,  what  its  precision  is). 

String  variable  names  are  written  with  a  dollar  sign 
($)  as  the  last  character.  For  example: 

A$  -  "SALES  REPORT11 

The  dollar  sign  is  a  variable  type  declaration 
character.  It  "declares"  that  the  variable  will 
represent  a  string. 

Numeric  variable  names  may  declare  integer, 
single-,  or  double-precision  values.  Although  you 
may  get  less  accuracy  doing  computations  with 
integer  and  single-precision  variables,  there  are 
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reasons  you  might  want  to  declare  a  variable  as  a 
particular  precision. 

•     Variables  of  higher  precisions  take  up  more 
room  in  storage.  This  is  important  if  space  is  a 
consideration. 


•     It  takes  more  time  for  the  computer  to  do 
arithmetic  with  the  higher  precision  numbers. 
A  program  with  repeated  calculations  will  run 
faster  with  integer  variables. 


The  type  declaration  characters  for  numeric 
variables  and  the  number  of  bytes  required  to  store 
each  type  of  value  are  as  follows: 


%     Integer  variable  (2  bytes) 


Single-precision  variable  (4  bytes) 


#     Double-precision  variable  (8  bytes) 

If  the  variable  type  is  not  explicitly  declared,  then  it 
will  default  to  single-precision. 


Examples  of  BASIC  variable  names  follow. 


PI#  declares  a  double-precision  value 

MINIMUM!  declares  a  single-precision  value 

LIMIT%  declares  an  integer  value 

N$  declares  a  string  value 

ABC  represents  a  single-precision  value 


Variable  tvpes  mav  also  be  declared  in  another  way. 
The  BASIC  statements  DEFINT,  DEFSNG, 
DEFDBL  and  DEFSTR  may  be  included  in  a 
program  to  declare  the  types  for  certain  variable 
names.  These  statements  are  described  in  detail 
under  "DEFtype  Statements"  in  Chapter  4.  All  the 
examples  which  follow  in  this  book  assume  that 
none  of  these  types  of  declarations  have  been  made, 
unless  the  statements  are  explicitly  shown  in  the 
example. 


Arrays 

An  array  is  a  group  or  table  of  values  that  are  referred 
to  with  one  name.  Each  individual  value  in  the  array 
is  called  an  element.  Array  elements  are  variables  and 
can  be  used  in  expressions  and  in  any  BASIC 
statement  or  function  which  uses  variables. 

Declaring  the  name  and  type  of  an  array  and  setting 
the  number  of  elements  and  their  arrangement  in 
the  array  is  known  as  defining,  or  dimensioning,  the 
array.  Usually  this  is  done  using  the  DIM  statement. 
For  example, 


This  creates  a  one  dimensional  array  named  B$.  All 
its  elements  are  variable  length  strings,  and  the 
elements  have  an  initial  null  value. 


This  creates  a  two-dimensional  array  named  A.  Since 
the  name  does  not  have  a  type  declaration  character, 
the  array  consists  of  single-precision  values.  All  the 
array  elements  are  initially  set  to  0. 

Each  array  element  is  named  with  the  array  name 
subscripted  with  a  number  or  numbers.  An  array 
variable  name  has  as  many  subscripts  as  there  are 
dimensions  in  the  array. 

The  subscript  indicates  the  position  of  the  element 
in  the  array.  Zero  is  the  lowest  position  unless  you 
explicitly  change  it  (see  "OPTION  BASE 
Statement"  in  Chapter  4).  The  maximum  number  of 
dimensions  for  an  array  is  255.  The  maximum 
number  of  elements  per  dimension  is  32767. 
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To  continue  the  preceding  examples,  array  B$  could 
be  thought  of  as  a  list  of  character  strings,  like  this: 


BS(0) 


B$(  1 ) 


B$(2) 


BS(3) 


BS(4) 


B$(5) 


The  first  string  in  the  list  is  named  B$(0). 

The  array  A  could  be  thought  of  as  a  table  of  rows  and 
columns,  like  this: 


columns 


A(0,0) 

A(0J) 

A(0.2) 

MO  3) 

A(  1,0) 

Ad.l  ) 

A(  1,2) 

M  1 ,3 ) 

A<2,0) 

A(2,l) 

A(2,2) 

A(2,3) 

The  element  in  the  second  row,  first  column,  is 
called  A(1,0). 

If  you  use  an  array  element  before  you  define  the 
array,  it  is  assumed  to  be  dimensioned  with  a 
maximum  subscript  of  10. 

For  example,  if  BASIC  encounters  the  statement: 

50  5IS('3.)---500 


and  the  array  SIS  has  not  already  been  defined,  the 
array  is  set  to  a  one-dimensional  array  with  11 
elements,  numbered  SIS(O)  through  SIS(IO).  You 
may  only  use  this  method  of  implicit  declaration  for 
one-dimensional  arrays. 

One  final  example: 


Ok 
10 
2d 
30 
40 
50 

60 
70 
80 
RUN 

0 

0 

0 

0 
Ok 


C I M  YEARS (3  ,A  J 

V  EARS  12 ,3)  =  1982 

FOR  ROW=0  TO  3 

FOR  COLUMNS  TO  h 

PR  I  NT  YEARS ( ROW  ,  COLUMN) 

NEXT  COLUMN 

i-  R  I  NT 

NEXT  ROW 


0  0  0  0 

0  0  0  0 

0  0  1982  0 

0  0  0  0 


3-17 


How  BASIC  Converts  Numbers  from 
One  Precision  to  Another 


When  necessary,  BASIC  will  convert  a  number  from 
one  precision  to  another.  The  following  rules  and 
examples  should  be  kept  in  mind. 

1 .  If  a  numeric  value  of  one  precision  is  assigned  to 
a  numeric  variable  of  a  different  precision,  the 
number  will  be  stored  as  the  precision  declared 
in  the  target  variable  name. 

Example: 


2.     Rounding,  as  opposed  to  truncation,  occurs 
when  assigning  any  higher  precision  value  to  a 
lower  precision  variable  (for  example,  changing 
from  double-  to  single-precision). 

Example: 

f k 

10  C  -  55.883-56/ 

7'i    rR    \\\  C 

D|  jK.I 

5c.HMm6 


This  affects  not  only  assignment  statements 
(e.g.,  I%=2.5  results  in  I%=3),  but  also  affects 
function  and  statement  evaluations 
(e.g.,  TAB(4.5)  goes  to  the  fifth  position,  A(l  .5) 
is  the  same  as  A(2),  and  X=l  1.5  MOD  4  will 
result  in  a  value  of  0  for  X). 
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3.     If  you  convert  from  a  lower  precision  to  a  higher 
precision  number,  the  resulting  higher 
precision  number  cannot  be  any  more  accurate 
than  the  lower  precision  number.  For  example, 
if  you  assign  a  single-precision  value  (A)  to  a 
double-precision  variable  (B#),  only  the  first  six 
digits  of  B#  will  be  accurate  because  only  six 
digits  of  accuracy  were  supplied  with  A.  The 
error  can  be  bounded  using  the  following 
formula: 


That  is,  the  absolute  value  of  the  difference 
between  the  printed  double-precision  number 
and  the  original  single-precision  value  is  less 
than  6.3E-8  times  the  original  single-precision 
value. 

Example: 


B 
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When  an  expression  is  evaluated,  all  of  the 
operands  in  an  arithmetic  or  relational 
operation  are  converted  to  the  same  degree  of 
precision,  namely  that  of  the  most  precise 
operand.  Also,  the  result  of  an  arithmetic 
operation  is  returned  to  this  degree  of 
precision. 

Examples: 

0  k 

10  D"  -  6-/7 
20  PRINT  0- 
RUN 

.8571^28571^28571 

Ok 

The  arithmetic  was  performed  in 
double-precision  and  the  result  was  returned  in 
D#  as  a  double-precision  value. 

10  0  =  6---Z7 

20  PRINT  D 
RUN 

Ok 

The  arithmetic  was  performed  in 
double-precision  and  the  result  was  returned  to 
D  (single-precision  variable),  rounded,  and 
printed  as  a  single-precision  value. 

Logical  operators  (see  "Logical  Operators"  in 
this  chapter)  convert  their  operands  to  integers 
and  return  an  integer  result.  Operands  must  be 
in  the  range  -32768  to  32767  or  an  "Overflow" 
error  occurs. 


Numeric  Expressions  and  Operators 


A  numeric  expression  may  be  simply  a  numeric 
constant  or  variable.  It  may  also  be  used  to  combine 
constants  and  variables  using  operators  to  produce  a 
single  numeric  value. 

Numeric  operators  perform  mathematical  or  logical 
operations  mostly  on  numeric  values,  and 
sometimes  on  string  values.  We  refer  to  them  as 
"numeric"  operators  because  they  produce  a  value 
that  is  a  number.  The  BASIC  numeric  operators  may 
be  divided  into  categories  as  follows: 

•  Arithmetic 

•  Relational 

•  Logical 

•  Functions 


Arithmetic  Operators 


The  arithmetic  operators  perform  the  usual 
operations  of  arithmetic,  such  as  addition  and 
subtraction.  In  order  of  precedence,  they  are: 


Operator  Operation 

Exponentiation 
Negation 


*,  /  Multiplication, 
Floating  Point 
Division 

\  Integer  Division 

MOD      Modulo  Arithmetic 

+,  -  Addition, 

Subtraction 


Sample  Expression 

X~  Y 

-X 

X*Y 
X/Y 

X\Y 

X  MOD  Y 

X-fY 
X  Y 
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(If  you  have  a  mathematical  background,  you  will 
notice  that  this  is  the  standard  order  of  precedence.) 
Although  most  of  these  operations  probably  look 
familiar  to  you,  two  of  them  may  seem  a  bit 
unfamiliar  —  integer  division  and  modulo 
arithmetic. 

Integer  Division:    Integer  division  is  denoted  by 
the  backslash  (\).  The  operands  are  rounded  to 
integers  (in  the  range  -32768  to  32767)  before  the 
division  is  performed;  the  quotient  is  truncated  to  an 
integer. 


For  example; 

Ok 

10  A  -  10  h 

20  B  =  25.68  6.99 

30  PRINT  A; B 

RUN 

2  3 
Ok 


Modulo  Arithmetic:    Modulo  arithmetic  is 
denoted  by  the  operator  MOD.  It  gives  the  integer 
value  that  is  the  remainder  of  an  integer  division. 

For  example: 

Ok 

10  A  =  7  MOD  k 
20  PRINT  A 

RUN 

3 
Ok 

This  result  occurs  because  7/4  is  1 ,  with  remainder  3. 

Ok 

PRINT  25.68  MOD  6.99 
5 

Ok 
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The  result  is  5  because  26/7  is  3,  with  the  remainder 
5.  (Remember,  BASIC  rounds  when  converting  to 
integers.) 


Relational  Operators 


Relational  operators  compare  two  values.  The 
values  may  be  either  both  numeric,  or  both  string. 
The  result  of  the  comparison  is  either  "true"  (-1)  or 
"false"  (0).  This  result  is  usually  then  used  to  make  a 
decision  regarding  program  flow.  (See  "IF 
Statement"  in  Chapter  4.) 

Operator   Relation  Tested    Sample  Expressions 


Equality 

X=Y 

<> 

or  >< 

Inequality 

XOY 
XXY 

< 

Less  than 

X<Y 

> 

Greater  than 

X>Y 

<= 

or  --< 

Less  than  or 
equal  to 

X<=Y 
X=<Y 

>= 

or  => 

Greater  than  or 
equal  to 

X>=Y 
X=>Y 

(The  equal  sign  is  also  used  to  assign  a  value  to  a 
variable.  See  "LET  Statement"  in  Chapter  4.) 

Numeric  Comparisons:    When  arithmetic  and 
relational  operators  are  combined  in  one 
expression,  the  arithmetic  is  always  performed  first. 
For  example,  the  expression: 

>:  >    ■   1  t  - 1  i  /  z 

will  be  true  (- 1 )  if  the  value  of  X  plus  Y  is  less  than  the 
value  of  T-l  divided  by  Z. 


3-23 


More  examples: 

Ok 

10  X--100 

2Q    ! F  X  -  ■  200  THEN  PRINT  "NOT  EQUAL 
ELSE   PRINT  "EQUAL" 

RUN 

NOT  EQUAL 
Ok 


Here,  the  relation  is  true  (100  is  not  equal  to  200). 
The  true  result  causes  the  THEN  part  of  the  IF 
statement  to  be  executed. 


01- 

PRINT   5  ■  2  ;  5-10 
0  -1 

0!- 


Here  the  first  result  is  false  (zero)  because  5  is  not 
less  than  2.  The  second  result  is  -1  because  the 
expression  5<10  is  true. 


String  Comparisons:    String  comparisons  can  be 
thought  of  as  "alphabetical."  That  is,  one  string  is 
"less  than"  another  if  the  first  string  comes  before 
the  other  one  alphabetically.  Lowercase  letters  are 
"greater  than"  their  uppercase  counterparts. 
Numbers  are  "less  than"  letters. 

The  way  two  strings  are  actually  compared  is  by 
taking  one  character  at  a  time  from  each  string  and 
comparing  the  ASCII  codes.  (See  "Appendix  G. 
ASCII  Character  Codes"  for  a  complete  list  of  ASCII 
codes.)  If  all  the  ASCII  codes  are  the  same,  the 
strings  are  equal.  Otherwise,  as  soon  as  the  ASCII 
codes  differ,  the  string  with  the  lower  code  number  is 
less  than  the  string  with  the  higher  code  number.  If, 
during  string  comparison,  the  end  of  one  string  is 
reached,  the  shorter  string  is  said  to  be  smaller. 


Leading  and  trailing  blanks  are  significant.  For 
example,  all  the  following  relational  expressions  are 
true  (that  is,  the  result  of  the  relational  operation  is 
-1). 


"AA"  -  "AB" 

nFI LE  NAME"   -    "  F  I L  E NAME 

"X>."    ■  "X**" 
"WR  "  •■  "WRM 
"kcj"    ■  "AG" 
' 1 S M Y  EH"   -•  "SMYTHE" 
B$  ■  "/l3" 


All  string  constants  used  in  comparison  expressions 
must  be  enclosed  in  quotation  marks. 


Logical  Operators 

Logical  operators  perform  logical,  or  Boolean, 
operations  on  numeric  values.  Just  as  the  relational 
operators  are  usually  used  to  make  decisions 
regarding  program  flow,  logical  operators  are 
usually  used  to  connect  two  or  more  relations  and 
return  a  true  or  false  value  to  be  used  in  a  decision 
(see  "IF  Statement"  in  Chapter  4). 

A  logical  operator  takes  a  combination  of  true-false 
values  and  returns  a  true  or  false  result.  An  operand 
of  a  logical  operator  is  considered  to  be  "true"  if  it  is 
not  equal  to  zero  (like  the  -1  returned  by  a  relational 
operator),  or  "false"  if  it  is  equal  to  zero.  The  result 
of  the  logical  operation  is  a  number  which  is,  again, 
"true"  if  it  is  not  equal  to  zero,  or  "false"  if  it  is  equal 
to  zero.  The  number  is  calculated  by  performing  the 
operation  bit  by  bit.  This  is  explained  in  detail 
shortly. 

The  logical  operators  are  NOT  (logical 
complement),  AND  (conjunction),  OR 
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(disjunction),  XOR  (exclusive  or),  IMP 
(implication),  and  EQV  (equivalence).  Each 
operator  returns  results  as  indicated  in  the  following 
table.  ("T"  indicates  a  true,  or  non-zero  value.  "F" 
indicates  a  false,  or  zero  value.)  The  operators  are 
listed  in  order  of  precedence. 


NOT 


AND 


OR 


XOR 


EQV 


IMP 
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Some  examples  of  ways  to  use  logical  operators  in 
decisions: 


Here,  the  result  will  be  true  if  the  value  of  the 
variable  HE  is  more  than  60  and  also  the  value  of 
SHE  is  less  than  20. 


The  result  will  be  true  if  I  is  greater  than  10,  or  K  is 
less  than  0,  or  both. 


Here,  the  program  will  branch  to  line  100  if  P  is  not 
equal  to  -1 .  Note  that  NOT  (P=-l)  does  not  produce 
the  same  result  as  NOT  P.  Refer  to  the  next  section, 
"How  Logical  Operators  Work,"  for  an  explanation. 


This  example  switches  a  value  back  and  forth  from 
true  to  false. 


How  Logical  Operators  Work:    Operands  are 
converted  to  integers  in  the  range  -32768  to  +32767. 
(If  the  operands  are  not  in  this  range,  an  "Overflow" 
error  results.)  If  the  operand  is  negative,  the  two's 
complement  form  is  used.  This  turns  each  operand 
into  a  sequence  of  16  bits.  The  operation  is 
performed  on  these  sequences.  That  is,  each  bit  of 
the  result  is  determined  by  the  corresponding  bits  in 
the  two  operands,  according  to  the  tables  for  the 
operator  listed  previously.  A  1  bit  is  considered 
"true",  and  a  0  bit  is  "false." 
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Thus,  you  can  use  logical  operators  to  test  for  a 
particular  bit  pattern.  For  instance,  the  AND 
operator  may  be  used  to  "mask"  all  but  one  of  the 
bits  of  a  status  byte  at  a  machine  I/O  port. 

The  following  examples  will  help  demonstrate  how 
the  logical  operators  work. 

A  -  63  AND  16 

Here,  A  is  set  to  16.  Since  63  is  binary  111111  and  16 
is  binary  10000,63  AND  16  equals  01 0000  in  binary, 
which  is  equal  to  16. 


B  -  -  I   AND  8 

B  is  set  to  8.  Since  -1  is  binary  11111111  11111111 
and  8  is  binary  1000,  -1  AND  8  equals  binary 
00000000  00001000,  or  8. 

C  -  !\  OR  2 

Here,  C  equals  6.  Since  4  is  binary  1 00  and  2  is  binary 
010,  4  OR  2  is  binary  110,  which  is  equal  to  6. 


X  --  2 

TWOSCOMP  -   (NOT  X)    4  1 

This  example  shows  how  to  form  the  two's 
complement  of  a  number.  X  is  2,  which  is  10  binary. 
NOT  X  is  then  binary  11111111  11111101,  which  is 
-3  in  decimal;  -3  plus  1  is  -2,  the  complement  of  2. 
That  is,  the  two's  complement  of  any  integer  is  the 
bit  complement  plus  one. 

Note  that  if  both  operands  are  equal  to  eitherO  or-1 , 
a  logical  operator  will  return  either  0  or-1. 


Numeric  Functions 


A  function  is  used  like  a  variable  in  an  expression  to 
call  a  predetermined  operation  that  is  to  be 
performed  on  one  or  more  operands.  BASIC  has 
"built-in"  functions  that  reside  in  the  system,  such  as 
SQR  (square  root)  or  SIN  (sine).  All  of  BASICs 
built-in  functions  are  listed  under  "Functions  and 
Variables"  in  the  beginning  of  Chapter  4.  Detailed 
descriptions  are  also  included  in  the  alphabetical 
section  of  Chapter  4. 


You  can  also  define  your  own  functions  using  the 
DEF  FN  statement.  See  "DEF  FN  Statement"  in 
Chapter  4. 


Order  of  Execution 


The  categories  of  numeric  operations  were 
discussed  in  their  order  of  precedence,  and  the 
precedence  of  each  operation  within  a  category  was 
indicated  in  the  discussion  of  the  category.  In 
summary: 


1.     Function  calls  are  evaluated  first 


2.     Arithmetic  operations  are  performed  next,  in 
this  order: 


a. 

b.  unary  - 

c.  *,  / 

d.  \ 

e.  MOD 

f.  +,  - 

3.     Relational  operations  are  done  next 
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4.     Logical  operations  are  done  last,  in  this  order: 


a.  NOT 

b.  AND 

c.  OR 

d.  XOR 

e.  EQV 

f.  IMP 


Operations  at  the  same  level  in  the  list  are  performed 
in  left-to- right  order.  To  change  the  order  in  which 
the  operations  are  performed,  use  parentheses. 
Operations  within  parentheses  are  performed  first. 
Inside  parentheses,  the  usual  order  of  operations  is 
maintained. 

Here  are  some  sample  algebraic  expressions  and 
their  BASIC  counterparts. 

Algebraic  Expression         BASIC  Expression 


X+2Y 


X+Y*2 


X-  Y 
Z 


X-Y/2 


XY 
Z 


X*Y/Z 


X+Y 
Z 


(X+Y)/Z 


(X~) 


(X~2)"Y 


Y 


Z 


X~(YAZ) 


X 


X(-Y) 


X*(-Y) 


Note:    Two  consecutive  operators  must  be 
separated  by  parentheses,  as  shown  in  the 
X*(-Y)  example. 


String  Expressions  and  Operators 


A  string  expression  may  be  simply  a  string  constant 
or  variable,  or  it  may  combine  constants  and 
variables  by  using  operators  to  produce  a  single 
string  value. 

String  operators  are  used  to  arrange  character 
strings  in  different  ways.  The  two  categories  of  string 
operators  are: 


•  Concatenation 


Functions 


Note  that  although  you  can  use  the  relational 
operators  =,  <>,  <,  >,  <=,  and  >=  to  compare  two 
strings,  these  are  not  considered  to  be  "string 
operators"  because  they  produce  a  numeric  result, 
not  a  string  result.  Read  through  "Relational 
Operators"  earlier  in  this  chapter  for  an  explanation 
of  how  you  can  compare  strings  using  relational 
operators. 


Concatenation 


Joining  two  strings  together  is  called  concatenation. 
Strings  are  concatenated  using  the  plus  symbol  (+). 
For  example: 
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String  Functions 


A  string  function  is  like  a  numeric  function  except 
that  it  returns  a  string  result.  A  string  function  can  be 
used  in  an  expression  to  call  a  predetermined 
operation  that  is  to  be  performed  on  one  or  more 
operands.  BASIC  has  "built-in"  functions  that  reside 
in  the  system,  such  as  MID$,  which  returns  a  string 
from  the  middle  of  another  string,  or  CHR$,  which 
returns  the  character  with  the  specified  ASCII  code. 
All  of  BASIC's  built-in  functions  are  listed  under 
"Functions  and  Variables"  in  the  beginning  of 
Chapter  4.  Detailed  descriptions  are  also  included  in 
the  alphabetical  section  of  Chapter  4. 

You  can  also  define  your  own  functions  using  the 
DEF  FN  statement.  See  "DEF  FN  Statement"  in 
Chapter  4. 
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Input  and  Output 


The  remainder  of  this  chapter  contains  information 
on  input  and  output  (I/O)  in  BASIC.  The  following 
topics  are  addressed: 

•     Files  —  how  BASIC  uses  files,  how  to  name  files, 
and  device  names 


•  The  screen  —  ways  to  display  things  on  the 
screen,  with  emphasis  on  graphics 

•  Other  features  —  clock,  sound,  light  pen,  and 
joysticks 


Files 


A  file  is  a  collection  of  information  which  is  kept 
somewhere  other  than  in  the  random  access  memory 
of  the  IBM  Personal  Computer.  For  example,  your 
information  may  be  stored  in  a  file  on  diskette  or 
cassette.  In  order  to  use  the  information,  you  must 
open  the  file  to  tell  BASIC  where  the  information  is. 
Then  you  may  use  the  file  for  input  and/or  output. 

BASIC  supports  the  concept  of  general  device  I/O 
files.  This  means  that  any  type  of  input/output  may 
be  treated  like  I/O  to  a  file,  whether  you  are  actually 
using  a  cassette  or  diskette  file,  or  are 
communicating  with  another  computer. 


File  Number:    BASIC  performs  I/O  operations 
using  a  file  number.  The  file  number  is  a  unique 
number  that  is  associated  with  the  actual  physical  file 
when  it  is  opened.  It  identifies  the  path  for  the 
collection  of  data.  A  file  number  may  be  any 
number,  variable,  or  expression  ranging  from  1  ton, 
where  n  is  the  maximum  number  of  files  allowed,  n  is 
4  in  Cassette  BASIC,  and  defaults  to  3  in  Disk  and 
Advanced  BASIC.  It  may  be  changed,  up  to  a 
maximum  of  1.5,  by  using  the  /F:  option  on  the 
BASIC  command  for  Disk  and  Advanced  BASIC. 
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Naming  Files 


The  physical  file  is  described  by  its  file  specification,  or 
filespec  for  short. 

The  file  specification  is  a  string  expression  of  the 
form: 

device.filename 

The  device  name  tells  BASIC  where  to  look  for  the 
file,  and  the  filename  tells  BASIC  which  file  to  look 
for  on  that  particular  device.  Sometimes  you  do  not 
need  both  device  name  and  filename,  so 
specification  of  device  and  filename  is  optional. 
Note  the  colon  (:)  indicated  above.  Whenever  you 
specify  a  device,  you  must  use  the  colon  even  though 
a  filename  is  not  necessarily  specified.  From  now  on 
we  will  include  the  colon  as  part  of  the  device  name. 

Note:    File  specification  for  communications 
devices  is  slightly  different.  The  filename  is 
replaced  with  a  list  of  options  specifying  such 
things  as  line  speed.  Refer  to  "OPEN  "COM... 
Statement"  in  Chapter  4  for  details. 

Remember  that  if  you  use  a  string  constant  for  the 
filespec,  you  must  enclose  it  in  quotation  marks.  For 
example, 

LU,'D    13  :  RO  1  HE  RM  .  ARK1 1 

Device  Name:  The  device  name  consists  of  up  to 
four  characters  followed  by  a  colon  (:).  The  following 
is  a  complete  list  of  device  names,  telling  what  device 
the  name  applies  to,  what  the  device  can  be  used  for 
(input  or  output),  and  which  versions  of  BASIC 
support  the  device. 


Device  Name  Chart 


KYBD:       Keyboard.  Input  only,  all  versions  of 
BASIC. 

SCRN:        Screen.  Output  only,  all  versions  of 
BASIC. 

LPTl:         First  printer.  Output,  all  versions;  or 
random,  Disk  and  Advanced  BASIC. 

LPT2:         Second  printer.  Output  or  random,  Disk 
and  Advanced  BASIC. 

LPT3:         Third  printer.  Output  or  random,  Disk 
and  Advanced  BASIC. 


COMMUNICATIONS  DEVICES 


COMl:       First  Asynchronous  Communications 

Adapter.  Input  and  output,  Disk  and 

Advanced  BASIC. 
COM2:       Second  Asynchronous  Communications 

Adapter.  Input  and  output,  Disk  and 

Advanced  BASIC. 


STORAGE  DEVICES 


CASl:         Cassette  tape  player.  Input  and  output, 
all  versions. 

A:  First  diskette  drive.  Input  and  output, 

Disk  and  Advanced  BASIC. 

B:  Second  diskette  drive.  Input  and  output, 

Disk  and  Advanced  BASIC. 


Refer  to  "Search  Order  for  Adapters"  in  "Appendix 
I.  Technical  Information  and  Tips"  for  information 
on  which  adapters  are  referred  to  by  the  printer  and 
communications  device  names. 
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Filename:    The  filename  must  conform  to  the 
following  rules. 

For  cassette  files: 

•  The  name  may  not  be  more  than  eight 
characters  long. 

•  The  name  may  not  contain  colons,  hex  'OO's  or 
hex  'FF's  (decimal  255s). 

For  diskette  files,  the  name  should  conform  to  DOS 
conventions: 

•  The  name  may  consist  of  two  parts  separated  by 
a  period  ( .  ): 

name,  extension 

The  name  may  be  from  one  to  eight  characters 
long.  The  extension  may  be  no  more  than  three 
characters  long. 

If  extension  is  longer  than  three  characters,  the 
extra  characters  are  truncated.  If  name  is  longer 
than  eight  characters  and  extension  is  not 
included,  then  BASIC  inserts  a  period  after  the 
eighth  character  and  uses  the  extra  characters 
(up  to  three)  for  the  extension.  If  name  is  longer 
than  eight  characters  and  an  extension  is 
included,  then  an  error  occurs. 

•  Only  the  following  characters  are  allowed  in 
name  and  extension: 

A  through  Z 
0  through  9 

<>()(} 
@  $    %    %  *    &  ! 


Some  examples  of  filenames  for  Disk  and  Advanced 
BASIC  are: 

27HAL. DAD 
VDL 

PROGRAM  1  . BAS 
^■(l)  .123 

The  following  examples  show  how  BASIC  truncates 
names  and  extensions  when  they  are  too  long,  as 
explained  above. 

A2  3^56789 J  KLMN    becomes:   A23^5678  .  9J  K 


SHERRY  LYNN . BAS 


■■  HOME  .  TRUM  1  0 


becomes 


causes  an  error 


■■HOME  .  TRU 
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Using  the  Screen 


BASIC  can  display  text,  special  characters,  points, 
lines,  or  more  complex  shapes  in  color  or  in  black 
and  white.  How  much  of  this  you  can  do  depends  on 
which  display  adapter  you  have  in  your  IBM  Personal 
Computer. 

Display  Adapters 

The  IBM  Personal  Computer  has  two  display 
adapters:  the  IBM  Monochrome  Display  and  Parallel 
Printer  Adapter,  and  the  Color/Graphics  Monitor 
Adapter. 

With  the  IBM  Monochrome  Display  and  Parallel 
Printer  Adapter,  you  can  display  text  in  black  and 
white.  Text  refers  to  letters,  numbers,  and  all  the 
special  characters  in  the  regular  character  set.  You 
have  some  capability  to  draw  pictures  with  the 
special  line  and  block  characters.  You  can  also  create 
blinking,  reverse  image,  invisible,  highlighted,  and 
underscored  characters  by  setting  parameters  on  the 
COLOR  statement. 

The  Color/Graphics  Monitor  Adapter  also  operates 
in  text  mode,  but  it  allows  you  to  display  text  in  16 
different  colors.  (You  can  also  display  in  just  black 
and  white  by  setting  parameters  on  the  SCREEN  or 
COLOR  statements.)  You  also  get  complete 
graphics  capability  to  draw  complex  pictures.  This 
graphics  capability  makes  the  screen  all  points 
addressable  in  medium  and  high  resolution.  This  is 
more  versatile  than  the  ability  to  draw  with  the 
special  line  and  block  characters  which  you  have  in 
text  mode.  From  now  on,  the  term  graphics  will  refer 
only  to  this  special  capability  of  the  Color/Graphics 
Monitor  Adapter.  The  use  of  the  extended  character 
set  with  special  line  and  block  characters  will  not  be 
considered  graphics. 
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Text  Mode 

The  screen  can  be  pictured  like  this: 


Character 
Dosition  1 ,  1 


%  g  i 

i  i 


Characters  are  shown  in  25  horizontal  lines  across 
the  screen.  These  lines  are  numbered  1  through  25, 
from  top  to  bottom.  Each  line  has  40  character 
positions  (or  80,  depending  on  how  you  set  the 
width).  These  are  numbered  1  to  40  (or  80)  from  left 
to  right.  The  position  numbers  are  used  by  the 
LOCATE  statement,  and  are  the  values  returned  by 
the  POS(0)  and  CSRLIN  functions.  For  example,  the 
character  in  the  upper  left  corner  of  the  screen  is  on 
line  1 ,  position  1 . 


Characters  are  normally  placed  on  the  screen  using 
the  PRINT  statement.  The  characters  are  displayed 
at  the  position  of  the  cursor.  Characters  are 
displayed  from  left  to  right  on  each  line,  from  line  1 
to  line  24.  When  the  cursor  would  normally  go  to 
line  25  on  the  screen,  lines  1  through  24  are  scrolled 
up  one  line,  so  that  what  was  line  1  disappears  from 
the  screen.  Line  24  is  then  blank,  and  the  cursor 
remains  on  line  24  to  continue  printing. 
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Line  25  is  usually  used  for  "soft  key"  display  (see 
"KEY  Statement"  in  Chapter  4),  but  it  is  possible  to 
write  over  this  area  of  the  screen  if  you  turn  the  "soft 
key"  display  off.  The  25  th  line  is  never  scrolled  by 
BASIC. 

Each  character  on  the  screen  is  composed  of  two 
parts:  foreground  and  background.  The  foreground 
is  the  character  itself.  The  background  is  the  "box" 
around  the  character.  You  can  set  the  foreground 
and  the  background  color  for  each  character  using 
the  COLOR  statement.  You  can  also  choose  to  make 
characters  blink. 

You  can  use  a  total  of  16  different  colors  if  you  have 
the  Color/Graphics  Monitor  Adapter: 


0 

Black 

8 

Gray 

1 

Blue 

9 

Light  Blue 

2 

Green 

10 

Light  Green 

3 

Cyan 

11 

Light  Cyan 

4 

Red 

12 

Light  Red 

5 

Magenta 

13 

Light  Magenta 

6 

Brown 

14 

Yellow 

7 

White 

15 

High-intensity  White 

The  colors  may  vary  depending  on  your  particular 
display  device.  Adjusting  the  color  tuning  of  the 
display  may  help  get  the  colors  to  match  this  chart 
better. 

Most  television  sets  or  monitors  have  an  area  of 
"overscan"  which  is  outside  the  area  used  for 
characters.  This  overscan  area  is  known  as  the  border 
screen.  You  can  also  use  the  COLOR  statement  to  set 
the  color  of  the  border  screen. 


The  statements  you  can  use  to  display  information  in 
text  mode  are: 


CLS  SCREEN 
COLOR  WIDTH 
1.0CA1E  WRITE 
PR  I  NT 

The  following  functions  and  system  variables  may  be 
used  in  text  mode: 

CSRLIN  SPC 
POS  TAB 
SCREEN 

Another  special  feature  you  get  in  text  mode  if  you 
have  the  Color/Graphics  Monitor  Adapter  is 
multiple  display  pages.  The  Color/ Graphics  Monitor 
Adapter  has  a  1 6K-byte  screen  buffer,  but  text  mode 
needs  only  2K  of  that  (or  4K  for  80  column  width). 
So  the  buffer  is  divided  into  different  pages,  which 
can  be  written  on  and/or  displayed  individually. 
There  are  8  pages,  numbered  0  to  7,  in  40  column 
width;  and  4  pages,  numbered  0  to  3,  in  80  column 
width.  Refer  to  "SCREEN  Statement"  in  Chapter  4 
for  details. 


Graphics  Modes 

The  graphics  modes  are  available  only  if  you  have  the 
Color/Graphics  Monitor  Adapter. 

You  can  use  BASIC  statements  to  draw  in  two 
graphic  resolutions: 

•  medium  resolution:  320  by  200  points  and  4 
colors 

•  high  resolution:  640  by  200  points  and  2  colors 

You  can  select  which  resolution  you  want  to  use  with 
the  SCREEN  statement. 
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The  statements  used  for  graphics  in  BASIC  are: 


C  i  RCLT 
COLOR 
DRAW 
GET 
L  I  NE 


PA  I  NT 

PRESET 

PSET 


PUT 

SCREEN 


The  only  graphics  function  is: 

PO  I  NT 


Medium  Resolution:    There  are  320  horizontal 
points  and  200  vertical  points  in  medium  resolution. 
These  points  are  numbered  from  left  to  right  and 
from  top  to  bottom,  starting  with  zero.  That  makes 
the  upper  left  corner  of  the  screen  point  (0,0),  and 
the  lower  right  corner  point  (319,199).  (If  you  are 
familiar  with  the  usual  mathematical  method  for 
numbering  coordinates,  this  may  seem  upside-down 
to  you.) 

Medium  resolution  is  unusual  because  of  its  color 
features.  When  you  put  something  on  the  screen  in 
medium  resolution,  you  can  specify  a  color  number 
of  0,  1 ,  2,  or  3.  These  colors  are  not  fixed,  as  are  the 
16  colors  in  text  mode.  You  select  the  actual  color 
for  color  number  0  and  select  one  of  two  "palettes" 
for  the  other  three  colors  by  using  the  COLOR 
statement.  A  palette  is  a  set  of  three  actual  colors  to 
be  associated  with  the  color  numbers  1,  2  and  3.  If 
you  change  the  palette  with  a  COLOR  statement,  all 
the  colors  on  the  screen  change  to  match  the  new 
palette. 

You  can  still  display  text  characters  on  the  screen  when 
you  are  in  graphics  mode.  The  size  of  the  characters  will 
be  the  same  as  in  text  mode;  that  is,  25  lines  of  40 
characters,  in  medium  resolution,  the  foreground  will  be 
color  number  3,  and  the  background  will  be  color  number 
0.  If  you  are  not  using  a  U.S.  keyboard,  refer  to 
"GRAFTABL-Color/Graphics  Adapter  Characters"  in 
the  DOS  section  of  the  Guide  to  Operations. 
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High  Resolution:    In  high  resolution  there  are  640 
horizontal  points  and  200  vertical  points.  As  in 
medium  resolution,  these  points  are  numbered 
starting  with  zero  so  that  the  lower  right  corner 
point  is  (639,199). 

High  resolution  is  a  little  easier  to  describe  than 
medium  resolution  since  there  are  only  two  colors: 
black  and  white.  Black  is  always  0  (zero),  and  white  is 
always  1  (one). 

When  you  display  text  characters  in  high  resolution,  you 
get  80  characters  on  a  line.  The  foreground  color  is  1 
(one)  and  the  background  color  is  0  (zero).  So  characters 
will  always  be  white  on  black.  It  you  are  not  using  a  U.S. 
keyboard,  refer  to  "GRAFTABL-Color/Graphics  Adapter 
Characters"  in  the  DOS  section  of  the  Guide  to 
Operations. 

Specifying  Coordinates:  The  graphic  statements 
require  information  about  where  on  the  screen  you 
want  to  draw.  You  give  this  information  in  the  form 
of  coordinates.  Coordinates  are  generally  in  the 
form  (x,y),  where*  is  the  horizontal  position,  andj  is 
the  vertical  position.  This  form  is  known  as  absolute 
form,  and  refers  to  the  actual  coordinates  of  the  point 
on  the  screen,  without  regard  to  the  last  point 
referenced. 

There  is  another  way  to  indicate  coordinates,  known 
as  relative form .  Using  this  form  you  tell  BASIC  where 
the  point  is  relative  to  the  last  point  referenced.  This 
form  looks  like: 

'■  TEP  (xo/fct,Vo/fcf) 

You  indicate  inside  the  parentheses  the  offset  in  the 
horizontal  and  vertical  directions  from  the  last  point 
referenced. 

The  "last  point  referenced"  is  set  by  each  graphics 
statement.  When  we  discuss  these  statements  in 
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"Chapter  4.  BASIC  Commands,  Statements, 
Functions,  and  Variables,"  we  will  indicate  what 
each  statement  sets  as  the  last  point  referenced. 

Note:    Be  careful  about  drawing  beyond  the 
limits  of  the  Screen  with  any  graphics 
statement;  it  may  confuse  the  last  point 
referenced. 

This  example  shows  the  use  of  both  forms  of 
coordinates: 

100  SCREEN  1 

110  PSET   (200,100)    'absolute  form 

120  PSET  STEP    (10,-20)    'relative  form 

This  sets  two  points  on  the  screen.  Their  actual 
coordinates  are  (200,100)  and  (210,80). 

Other  I/O  Features 

Clock 

You  may  set  and  read  the  following  system  variables: 

DATE$  Ten-character  string  which  is  the 

system  date,  in  the  form  mm-dd-yyyy . 

TIME$  Eight-character  string  which  indicates 

the  time  as  hh:mm:ss. 


Sound  and  Music 

You  can  use  the  following  statements  to  create 
sound  on  the  IBM  Personal  Computer: 

BEEP  Beeps  the  speaker. 

SOUND        Makes  a  single  sound  of  given 
frequency  and  duration. 

PLAY  Plays  music  as  indicated  by  a  character 

string. 
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Light  Pen 


BASIC  has  the  following  statements  and  functions  to 
allow  input  from  a  light  pen. 

PEN  Function  which  tells  whether  or  not 

the  pen  was  triggered  and  gives  its 
coordinates. 


PEN  Statement  which  enables/disables 

light  pen  function. 

ON  PEN        Statement  to  trap  light  pen  activity. 


Joysticks 

Joysticks  can  be  useful  in  an  interactive 
environment.  BASIC  supports  two  2-dimensional 
(x  and  y  coordinate)  joysticks,  or  four 
one-dimensional  paddles,  each  of  which  has  a 
button.  (Four  buttons  are  supported  only  in 
Advanced  BASIC.)  The  following  statements  and 
functions  are  used  for  joysticks: 


STICK  Function  which  gives  the  coordinates 

of  the  joystick. 

STRIG  Function  which  gives  the  status  of  the 

joystick  button  (up  or  down). 

STRIG  Statement  which  enables/disables 

STRIG  function. 


ON  STRIG    Statement  used  to  trap  the  button 
being  pressed. 

STRIG(n)      Statement  which  enables/disables  the 
joystick  button  interrupt. 

Note:    The  light  pen  may  only  be  used  if  you 
have  a  Color/Graphics  Monitor  Adapter. 
Joysticks  may  only  be  used  if  you  have  a  Game 
Control  Adapter. 
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How  to  Use  This  Chapter 


Descriptions  of  all  the  BASIC  commands, 
statements,  functions,  and  variables  are  included  in 
this  chapter.  BASIC's  built-in  functions  and 
variables  may  be  used  in  any  program  without 
further  definition. 

The  first  several  pages  contain  lists  of  all  the 
commands,  statements,  functions,  and  variables. 
These  lists  may  be  useful  as  a  quick  reference.  The 
rest  of  the  chapter,  arranged  alphabetically, 
describes  each  command,  statement,  function,  and 
variable  in  more  detail. 

The  distinction  between  a  command  and  a  statement 
is  largely  a  matter  of  tradition.  Commands,  because 
they  generally  operate  on  programs,  are  usually 
entered  in  direct  mode.  Statements  generally  direct 
program  flow  from  within  a  program,  and  so  are 
usually  entered  in  indirect  mode  as  part  of  a  program 
line.  Actually,  most  BASIC  commands  and 
statements  can  be  entered  in  either  direct  or  indirect 
mode. 

The  description  of  each  command,  statement, 
function,  or  variable  in  this  chapter  is  formatted  as 
follows: 


Purpose:     Tells  what  the  command,  statement,  function,  or 
variable  does. 


Versions:   Indicates  which  versions  of  BASIC  allow  the 

command,  statement,  function,  or  variable.  For 
example,  if  you  look  under  "CHAIN  Statement"  in 
this  chapter,  you  will  note  that  after  Versions:  it 
says: 

Cassette       Disk      Advanced  Compiler 
***  ***  ^  *  #  ^ 

The  asterisks  indicate  which  versions  of  BASIC 
support  the  statement.  This  example  shows  that  you 
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can  use  the  CHAIN  statement  for  programs  written 
in  the  Disk  and  Advanced  versions  of  BASIC. 

In  this  example  you  will  notice  that  the  asterisks 
under  the  word  "Compiler"  are  in  parentheses.  This 
means  that  there  are  differences  between  the  way  the 
statement  works  under  the  BASIC  interpreter  and 
the  way  it  works  under  the  IBM  Personal  Computer 
BASIC  Compiler.  The  IBM  Personal  Computer 
BASIC  Compiler  is  an  optional  software  package 
available  from  IBM.  If  you  have  the  BASIC 
Compiler,  the  IBM  Persona/  Computer  BASIC  Compiler 
manual  explains  these  differences. 

Format:     Shows  the  correct  format  for  the  command, 
statement,  function,  or  variable.  A  complete 
explanation  of  the  syntax  format  is  presented  in 
the  Preface.  Remember  to  keep  these  rules  in 
mind. 

•  Words  in  capital  letters  are  keywords  and  must 
be  entered  as  shown.  They  may  be  entered  in 
any  combination  of  uppercase  and  lowercase 
letters.  BASIC  always  converts  words  to 
uppercase  (unless  they  are  part  of  a  quoted 
string,  remark,  or  DATA  statement). 

•  You  are  to  supply  any  items  in  lowercase  italic 
letters. 

•  Items  in  square  brackets  (  [  ]  )  are  optional. 

•  An  ellipsis  (...)  indicates  an  item  may  be 
repeated  as  many  times  as  you  wish. 

•  All  punctuation  except  square  brackets  (such  as 
commas,  parentheses,  semicolons,  hyphens,  or 
equal  signs)  must  be  included  where  shown. 


Remarks:    Describes  in  detail  how  the  command,  statement, 
function,  or  variable  is  used. 


Example:  Shows  direct  mode  statements,  sample  programs,  or 
program  segments  that  demonstrate  the  use  of  the 
command,  statement,  function,  or  variable. 
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In  the  formats  given  in  this  chapter,  some  of  the 
parameters  have  been  abbreviated  as  follows: 

x,  y,  z        represent  any  numeric  expressions 

i,  j,  k,  m,  n  represent  integer  expressions 

x$,  y$        represent  string  expressions 

v,  v$  represent  numeric  and  string  variables, 

respectively 

If  a  single-  or  double-precision  value  is  supplied 
where  an  integer  is  required,  BASIC  rounds  the 
fractional  portion  and  uses  the  resulting  integer. 


Functions  and  Variables:    In  the  format 
description,  most  of  the  functions  and  variables  are 
shown  on  the  right  side  of  an  assignment  statement. 
This  is  to  remind  you  that  they  are  not  used  like 
statements  and  commands.  It  is  not  meant  to  suggest 
that  you  are  limited  to  using  them  in  assignment 
statements.  You  can  use  them  anywhere  you  would 
use  a  regular  variable,  except  on  the  left  side  of  an 
assignment  statement.  Any  exceptions  are  noted  in 
the  particular  section  describing  the  function  or 
variable.  A  few  of  the  functions  are  limited  to  being 
used  in  PRINT  statements;  these  are  shown  as  part 
of  a  PRINT  statement. 

Note:    Only  integer  and  single-precision 
results  are  returned  by  the  numeric  functions, 
except  where  indicated  otherwise. 
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Commands 


The  following  is  a  list  of  all  the  commands  used  in 
BASIC.  The  syntax  of  each  command  is  shown,  but 
not  always  in  its  entirety.  You  can  find  detailed 
information  about  each  command  in  the 
alphabetical  part  of  this  chapter.  You  may  also  want 
to  check  the  next  section  in  this  chapter, 
"Statements,"  for  a  list  of  the  BASIC  statements. 

Command  Action 

AUTO  number,  increment 

Generates  line  numbers 
automatically. 

BLOAD  filespec,offset 

Loads  binary  data  (such  as  a 
machine  language  program) 
into  memory. 

BSAVE  filespec,offset,length 

Saves  binary  data. 

CLEAR  ,n,m  Clears  program  variables,  and 

optionally  sets  memory  area. 

CONT  Continues  program 

execution. 

DELETE  linel-line2  Deletes  specified  program 

lines. 

EDIT  line  Displays  a  program  line  for 

changing. 

FILES  filespec  Lists  files  in  the  diskette 

directory  that  match  a  file 
specification. 

KILL  filespec  Erases  a  diskette  file. 
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Command 


Action 


LIST  Hnel-line2,filespec 

Lists  program  lines  on  the 
screen  or  to  the  specified  file. 


LLIST  linel-line2 
LOAD  filespec 
MERGE  filespec 


Lists  program  lines  on  the 
printer. 

Loads  a  program  file.  Can 
include  the  R  option  to  run  it. 

Merges  a  saved  program  with 
the  program  in  memory. 


NAME  filespec  AS  filename 

Renames  a  diskette  file. 


NEW 


Erases  the  current  program 
and  variables. 


RENUM  newnum,oldnum,increment 

Renumbers  program  lines. 


RESET 

RUN  filespec 

RUN  line 
SAVE  filespec 

SYSTEM 
TRON,  TROFF 


Reinitializes  diskette 
information.  Similar  to 
CLOSE. 

Executes  a  program.  The  R 
option  may  be  used  to  keep 
files  open. 

Runs  the  program  in  memory 
starting  at  the  specified  line. 

Saves  the  program  in  memory 
under  the  given  filename.  A 
or  P  option  saves  in  ASCII  or 
protected  format. 

Ends  BASIC.  Closes  all  files 
and  returns  to  DOS. 

Turns  trace  on  or  off. 
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Statements 


This  section  lists  all  the  BASIC  statements 
alphabetically  in  two  categories:  1/ O  (Input/Output) 
Statements  and  Non-I/O  Statements.  The  list  tells 
what  each  statement  does  and  shows  the  syntax.  For 
the  more  complex  statements  the  syntax  shown  may 
not  be  complete.  You  can  find  detailed  information 
about  each  statement  in  the  alphabetical  portion  of 
this  chapter,  later  on. 

You  may  also  want  to  look  at  the  previous  section, 
"Commands,"  for  a  list  of  the  BASIC  commands. 


Non-I/O  Statements 

Statement  Action 

CALL  numvar(variable  list) 

Calls  a  machine  language 
program. 

CHAIN  filespec         Calls  a  program  and  passes 

variables  to  it.  Other  options 
allow  you  to  use  overlays, 
begin  running  at  a  line  other 
than  the  first  line,  pass  all 
variables,  or  delete  an 
overlay. 

COM(n)  ON/OFF/STOP 

Enables  and  disables  trapping 
of  communications  activity. 

COMMON  list  of  variables 

Passes  variables  to  a  chained 
program. 

DATE$  =  x$  Sets  the  date. 

DEF  FNname(arg  list)=expression 

Defines  a  numeric  or  string 
function. 
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Statement 


Action 


DEFtype  ranges  of  letters 

Defines  default  variable 
types,  where  type  is  INT, 
SNG,  DBL,  or  STR. 

DEF  SEG=address     Defines  current  segment  of 

memory. 

DEF  USRn=offset     Defines  starting  address  for 

machine  language  subroutine 
n. 

DIM  list  of  subscripted  variables 

Declares  maximum  subscript 
values  for  arrays  and  allocates 
space  for  them. 

END  Stops  the  program,  closes  all 

files,  and  returns  to  command 
level. 

ERASE  arraynames    Eliminates  arrays  from  a 

program. 

ERROR  n  Simulates  error  number  n. 

FOR  variable=x  TO  y  STEP  z 

Repeats  program  lines  a 
number  of  times.  The  NEXT 
statement  closes  the  loop. 

GOSUB  line  Calls  a  subroutine  by 

branching  to  the  specified 
line.  The  RETURN 
statement  returns  from  the 
subroutine. 

GOTO  line  Branches  to  the  specified 

line. 
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Statement 


Action 


IF  expression  THEN  clause  ELSE  clause 

Performs  the  statement(s)  in 
the  THEN  clause  if 
expression  is  true  (nonzero). 
Otherwise,  performs  the 
ELSE  clause  or  goes  to  the 
next  line. 


KEY  ON/OFF/LIST  Displays  soft  keys  or  turns 

display  off. 


KEY  n,  x$ 


Sets  soft  key  n  to  the  value  of 
the  string  x$. 


KEY(n)  ON/OFF/STOP 

Enables/disables  trapping  of 
function  keys  or  cursor 
control  keys. 

LET  variable=expression 

Assigns  the  value  of  the 
expression  to  the  variable. 


MID$(v$,n,m)=y$ 


Replaces  part  of  the  variable 
v$  with  the  string  y$,  starting 
at  position  n  and  replacing  m 
characters. 


MOTOR  state 


Turns  cassette  motor  on  if 
state  is  nonzero,  off  if  state  is 
zero. 


NEXT  variable 


Closes  a  FOR... NEXT  loop 
(see  FOR). 


ON  COM(n)  GOSUB  line 

Enables  trap  routine  for 
communications  activity. 

ON  ERROR  GOTO  line 

Enables  error  trap  routine 
beginning  at  line  specified. 


Statement 


Action 


ON  n  GOSUB  line  list 

Branches  to  subroutine 
specified  by  n. 

ON  n  GOTO  line  list 

Branches  to  statement 
specified  by  n. 

ON  KEY(n)  GOSUB  line 

Enables  trap  routine  for  the 
specified  function  key  or 
cursor  control  key. 

ON  PEN  GOSUB  line 

Enables  trap  routine  for  light 
pen. 

ON  STRIG(n)  GOSUB  line 

Enables  trap  routine  for 
joystick  button. 

OPTION  BASE  n       Specifies  the  minimum  value 

for  array  subscripts, 

PEN  ON/OFF/STOP  Enables/disables  the  light  pen 

function. 


POKE  n,m 

RANDOMIZE  n 

REM  remark 
RESTORE  line 


Puts  byte  m  into  memory  at 
the  location  specified  by  n. 

Reseeds  the  random  number 
generator. 

Includes  remark  in  program. 

Resets  DATA  pointer  so 
DATA  statements  may  be 
reread. 


RESUME  line/NEXT/O 

Returns  from  error  trap 
routine. 
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Statement 
RETURN  line 
STOP 

STRIG  ON/OFF 


Action 

Returns  from  subroutine. 

Stops  program  execution, 
prints  a  break  message,  and 
returns  to  command  level. 

Enables/disables  joystick 
button  function. 


STRIG(n)  ON/OFF/STOP 

Enables/disables  joystick 
button  trapping. 

SWAP  variablel,variable2 

Exchanges  values  of  two 
variables. 


TIME$  =  x$ 
WAIT  port,n,m 

WEND 


Sets  the  time. 

Suspends  program  execution 
until  the  specified  port 
develops  the  specified  bit 
pattern. 

Closes  a  WHILE. ..WEND 
loop  (see  WHILE). 


WHILE  expression    Begins  a  loop  which  executes 

as  long  as  the  expression  is 
true. 


I/O  Statements 


Statement 
BEEP 

CIRCLE  (x,y),r 


CLOSE  #f 
CLS 


Action 

Beeps  the  speaker. 

Draws  a  circle  with  center 
(x,y)  and  radius  r.  Other 
options  allow  you  to  specify  a 
part  of  the  circle  to  be  drawn, 
or  to  change  the  aspect  ratio 
to  draw  an  ellipse. 

Closes  a  file. 

Clears  the  screen. 


COLOR  foreground,background,border 

In  text  mode,  sets  colors  for 
foreground,  background,  and 
the  border  screen. 

COLOR  background,palette 

In  graphics  mode,  sets 
background  color  and  palette 
of  foreground  colors. 

DATA  list  of  constants 

Creates  a  data  table  to  be  used 
by  READ  statements. 


DRAW  string 


Draws  a  figure  as  specified  by 
string. 


FIELD  #f, width  AS  stringvar... 

Defines  fields  in  a  random  file 
buffer. 


GET  #f, number 


Reads  a  record  from  a  random 
file. 


GET  (xl,yl)-(x2,y2),arrayname 

Reads  graphic  information 
from  screen. 
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Statement  Action 

INPUT  "prompt";variable  list 

Reads  data  from  the  keyboard. 

INPUT  #f, variable  list 

Reads  data  from  file  f. 

LINE  (xl,yl)-(x2,y2)  Draws  a  line  on  the  screen. 

Other  parameters  allow  you 
to  draw  a  box,  and  fill  the  box 
in. 

LINE  INPUT  "prompt";stringvar 

Reads  an  entire  line  from  the 
keyboard,  ignoring  commas 
or  other  delimiters. 

LINE  INPUT  #f,stringvar 

Reads  an  entire  line  from  a 
file. 

LOCATE  row,col       Positions  the  cursor.  Other 

parameters  allow  you  to 
define  the  size  of  the  cursor 
and  whether  it  is  visible  or 
not. 

LPRINT  list  of  expressions 

Prints  data  on  the  printer. 

LPRINT  USING  v$;list  of  expressions 

Prints  data  on  the  printer 
using  the  format  specified  by 
v$. 

LSET  stringvar=x$    Left-justifies  a  string  in  a  field. 

OPEN  filespec  FOR  mode  AS  #f 

Opens  the  file  for  the  mode 
specified.  Another  option 
sets  the  record  length  for 
random  files. 


Statement 


Action 


OPEN  mode,#f,filespec,recl 

Alternative  form  of  preceding 
OPEN. 

OPEN  "COMn:options"  AS  #f 

Opens  file  for 
communications. 


OUT  n,m 


Outputs  the  byte  m  to  the 
machine  port  n. 


PAINT  (x,y),paint,boundary 

Fills  in  an  area  on  the  screen 
defined  by  boundary  with  the 
paint  color. 


PLAY  string 


Plays  music  as  specified  by 
string. 


PRINT  list  of  expressions 

Displays  data  on  the  screen. 

PRINT  USING  v$,list  of  expressions 

Displays  data  using  the 
format  specified  by  v$. 

PRINT  #(,  list  of  exps 

Writes  the  list  of  expressions 
to  file  f. 

PRINT  #f,  USING  v$;list  of  exps 

Writes  data  to  file  f  using  the 
format  specified  by  v$. 


PRESET  (x,y) 
PSET  (x,y),color 

PUT  #f, number 


Draws  a  point  on  the  screen  in 
background  color.  See  PSET. 

Draws  a  point  on  the  screen, 
in  the  foreground  color  if 
color  is  not  specified. 

Writes  data  from  a  random 
file  buffer  to  the  file. 
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Statement 


Action 


PUT  (x,y),array,action 

Writes  graphic  information 
to  the  screen. 

READ  variable  list    Retrieves  information  from 

the  data  table  created  by 
DATA  statements. 

RSET  stringvar=x$    Right-justifies  a  string  in  a 

field.  See  LSET. 

SCREEN  mode,burst,apage,vpage 


SOUND  freq.duration 

Generates  sound  through  the 
speaker. 


WRITE  list  of  expressions 

Outputs  data  on  the  screen. 

WRITE  #f,  list  of  expressions 

Outputs  data  to  a  file. 


Sets  screen  mode,  color  on  or 
off,  display  page,  and  active 
page. 


WIDTH  size 


Sets  screen  width.  Other 
options  allow  you  to  specify 
the  width  of  a  printer  or  a 
communications  file. 


Functions  and  Variables 


The  built-in  functions  and  variables  available  in 
BASIC  are  listed  below,  grouped  into  two  general 
categories:  numeric  functions,  or  those  which 
return  a  numeric  result;  and  string  functions,  or 
those  which  return  a  string  result. 

Each  category  is  further  subdivided  according  to  the 
usage  of  the  functions.  The  numeric  functions  are 
divided  into  general  arithmetic  (or  algebraic) 
functions;  string-related  functions,  which  operate 
on  strings;  and  input/output  and  miscellaneous 
functions.  The  string  functions  are  separated  into 
general  string  functions,  and  input/output  and 
miscellaneous  string  functions. 

Note:    Only  integer  and  single-precision 
results  are  returned  by  the  numeric  functions, 
except  where  indicated  otherwise. 


Numeric  Functions  (return  a  numeric 
value) 

ARITHMETIC 


Function 


ABS(x) 


Returns  the  absolute  value  of 


Result 


x. 


ATN(x) 


Returns  the  arctangent  (in 
radians)  of  x. 


CDBL(x) 


Converts  x  to  a 
double-precision  number. 


CINT(x) 


Converts  x  to  an  integer  by 
rounding. 


COS(x) 


Returns  the  cosine  of  angle  x, 
where  x  is  in  radians. 


CSNG(x) 


Converts  x  to  a 
single-precision  number. 
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Function 


Result 


EXP(x)  Raises  e  to  the  x  power. 

FIX(x)  Truncates  x  to  an  integer. 

INT(x)  Returns  the  largest  integer  less 

than  or  equal  to  x. 

LOG(x)  Returns  the  natural  logorithm 

of  x. 

RND(x)  Returns  a  random  number. 

SGN(x)  Returns  the  sign  of  x. 

SIN(x)  Returns  the  sine  of  angle  x, 

where  x  is  in  radians. 

SQR(x)  Returns  the  square  root  of  x. 

TAN(x)  Returns  the  tangent  of  angle  x, 

where  x  is  in  radians. 

For  information  on  how  to  calculate  mathematical 
functions  which  are  n  )t  included  in  this  list,  refer  to 
"Appendix  E.  Mathematical  Functions." 

STRING-RELATED 

Function  Result 

ASC(x$)  Returns  the  ASCII  code  for  the 

first  character  in  x$. 

CVI(x$),  CVS(x$),  CVD(x$) 

Converts  x$  to  a  number  of  the 
indicated  precision. 

INSTR(n,x$,y$)        Returns  the  position  of  first 
occurrence  of  y$  in  x$  starting 
at  position  n. 

LEN(x$)  Returns  the  length  of  x$. 

VAL(x$)  Returns  the  numeric  value  of 

x$. 
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I/O  and  MISCELLANEOUS 


Function 
CSRLIN 

EOF(f) 

ERL 

ERR 

FRE(x$) 

INP(n) 
LOC(f) 


LOF(f) 


LPOS(n) 


Result 

Returns  the  vertical  line 
position  of  the  cursor. 

Indicates  an  end  of  file 
condition  on  file  f. 

Returns  the  line  number 
where  the  last  error  occurred 
(see  ERR). 

Returns  the  error  code 
number  of  the  last  error. 

Returns  the  amount  of  free 
space  in  memory  not  currently 
in  use  by  BASIC. 

Reads  a  byte  from  port  n. 

Returns  the  "location"  of  file  f: 

•  last  record  number  of 
random  file 

•  number  of  sectors  read  or 
written  for  sequential  file 

•  number  of  characters  in 
communications  input 
buffer 

Returns  the  length  of  file  f: 

•  number  of  bytes  (in 
multiples  of  128)  in 
sequential  or  random  file 

•  number  of  bytes  free  in 
communications  input 
buffer 

Returns  the  carriage  position 
of  the  printer. 
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Function  Result 

PEEK(n)  Reads  the  byte  in  memory 

location  n. 

PEN(n)  Reads  the  light  pen. 

POINT(x,y)  Returns  the  color  of  point  (x,y) 

(graphics  mode). 

POS(n)  Returns  the  cursor  column 

position. 

SCREEN(row,col,z)  Returns  the  character  or  color 
at  position  (row,col). 

STICK(n)  Returns  the  coordinates  of  a 

joystick. 

STRIG(n)  Returns  the  state  of  a  joystick 

button. 

USRn(x)  Calls  a  machine  language 

subroutine  with  argument  x. 

VARPTR(variable)  Returns  the  address  of  the 
variable  in  memory. 

VARPTR(#f)  Returns  the  address  of  the  file 

control  block  for  file  f. 


String  Functions  (return  a  string  value) 

GENERAL 


Function 
CHR$(n) 

LEFT$(x$,n) 

MID$(x$,n,m) 

RIGHT$(x$,n) 

SPACE$(n) 
STRING$(n,m) 

STRING$(n,x$) 


Result 

Returns  the  character  with 
ASCII  code  n. 

Returns  the  leftmost  n 
characters  of  x$. 

Returns  m  characters  from  x$ 
starting  at  position  n. 

Returns  the  rightmost  n 
characters  of  x$. 

Returns  a  string  of  n  spaces. 

Returns  the  character  with 
ASCII  value  m,  repeated  n 
times. 

Returns  the  first  character  of 
x$  repeated  n  times. 


I/O  and  MISCELLANEOUS 


Function 

DATE$ 

HEX$(n) 

INKEY$ 

INPUT$(n,#f) 


Result 

Returns  the  system  date. 

Converts  n  to  a  hexadecimal 
string. 

Reads  a  character  from  the 
keyboard. 

Reads  n  characters  from  file  f. 
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Function 


Result 


MKI$(x),  MKS$(x),  MKD$(x) 

Converts  x  in  indicated 
precision  to  proper  length 
string. 


OCT$(n) 
SPC(n) 

STR$(x) 
TAB(n) 

TIME$ 
VARPTR$(v) 


Converts  n  to  an  octal  string. 

Prints  n  spaces  in  a  PRINT  or 
LPRINT  statement. 

Converts  x  to  a  string  value. 

Tabs  to  position  n  in  a  PRINT 
or  LPRINT  statement. 

Returns  the  system  time. 

Returns  a  three-byte  string 
containing  the  type  of 
variable,  and  the  address  of  the 
variable  in  memory. 


ABS 
Function 


Purpose:     Returns  the  absolute  value  of  the  expression  x 


Versions:    Cassette       Disk      Advanced  Compiler 


Format:     v  =  ABS(x) 


Remarks:  x  may  be  any  numeric  expression. 

The  absolute  value  of  a  number  is  always  positive  or 
zero. 


Example:  qiv 

P  R  !  N  ' 


The  absolute  value  of -35  is  positive  35. 
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ASC 

Function 


Purpose:     Returns  the  ASCII  code  for  the  first  character  of  the 
string  x$. 


Versions:    Cassette       Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:     v  -  ASC(x$) 


Remarks:  x$  may  be  any  string  expression. 

The  result  of  the  ASC  function  is  a  numerical  value 
that  is  the  ASCII  code  of  the  first  character  of  the 
string  x$.  (See  "Appendix  G.  ASCII  Character 
Codes"  for  ASCII  codes.)  If  x$  is  null,  an  "Illegal 
function  call"  error  is  returned. 

The  CHR$  function  is  the  inverse  of  the  ASC 
function,  and  it  converts  the  ASCII  code  to  a 
character. 


Example:  Ok 

10  X$  =  "TEST11 
20  PRINT  ASC(X$) 
RUM 

Ok 

This  example  shows  that  the  ASCII  code  for  a  capital 
T  is  84.  Print  ASC("TEST")  would  work  just  as  well. 
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ATN 
Function 


Purpose:     Returns  the  arctangent  of  x. 


Versions:    Cassette      Disk       Advanced  Compiler 


Format:     v  =  ATN(jt) 


Remarks:  x     may  be  a  numeric  expression  of  any  numeric 
type,  but  the  evaluation  of  ATN  is  always 
performed  in  single  precision. 

The  ATN  function  returns  the  angle  whose  tangent 
is  jr.  The  result  is  a  value  in  radians  in  the  range  -PI/2 
to  PI/2,  where  PI=3. 141593. 

If  you  want  to  convert  radians  to  degrees,  multiply 
by  180/PI. 


Example: 


1  0  y  )---].  ]  q  i  33  '? 

2  0  RmD  !  />NS  =  ATN  :  1  ; 


The  first  example  shows  the  use  of  the  ATN  function 
to  calculate  the  arctangent  of  3.  The  second  example 
finds  the  angle  whose  tangent  is  1.  It  is  .785  3983 
radians,  or  45  degrees. 
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AUTO 
Command 


Purpose:     Generates  a  line  number  automatically  each  time 
you  press  Enter. 

Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  *** 


Format:      AUTO  [number]  [,  [increment]  ] 

Remarks:   number        is  the  number  which  will  be  used  to  start 

numbering  lines.  A  period  (.)  may  be 
used  in  place  of  the  line  number  to 
indicate  the  current  line, 

increment      is  the  value  that  will  be  added  to  each  line 
number  to  get  the  next  line  number. 

Numbering  begins  at  number  and  increments  each 
subsequent  line  number  by  increment.  If  both  values 
are  omitted,  the  default  is  10,10.  It  number  is  followed 
by  a  comma  but  increment  is  not  specified,  the  last 
increment  specified  in  an  AUTO  command  is 
assumed.  If  number  is  omitted  but  increment  is 
included,  then  line  numbering  begins  with  0. 

AUTO  is  usually  used  for  entering  programs.  It 
releases  you  from  having  to  type  each  line  number. 
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AUTO 
Command 


If  AUTO  generates  a  line  number  that  already  exists 
in  the  program,  an  asterisk  (*)  is  printed  after  the 
number  to  warn  you  that  any  input  will  replace  the 
existing  line.  However,  if  you  press  Enter 
immediately  after  the  asterisk,  the  existing  line  will 
not  be  replaced  and  AUTO  will  generate  the  next 
line  number. 

AUTO  ends  when  you  press  Ctrl-Break.  The  line  in 
which  Ctrl-Break  is  typed  is  not  saved.  After  a 
Ctrl-Break,  BASIC  returns  to  command  level. 

Note:    When  in  AUTO  mode,  you  may  make 
changes  only  to  the  current  line.  If  you  want  to 
change  another  line  on  the  screen,  be  sure  to 
exit  AUTO  by  first  pressing  Ctrl-Break. 


Example:  AUTO 

This  command  generates  line  numbers  10,  20,  30, 
40,  ... 

AUTO  100,50 

This  generates  line  numbers  100,  150,  200,  ... 

AUTO  500, 

This  generates  line  numbers  500,  550,  600,  650,  ... 
The  increment  is  50  since  50  was  the  increment  in 
the  previous  AUTO  command, 

AUTO  ,20 

This  generates  line  numbers  0,  20,  40,  60,  ... 
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BEEP 
Statement 


Purpose:     Beeps  the  speaker. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:  BEEP 


Remarks:   The  BEEP  statement  sounds  the  speaker  at  800  Hz 
for  1/4  second.  BEEP  has  the  same  effect  as: 


Example: 

In  this  example,  the  program  checks  to  see  if  X  is  out 
of  range.  If  it  is,  the  computer  "complains"  by 
beeping. 
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BLOAD 
Command 


Purpose:     Loads  a  memory  image  file  into  memory. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      BLOAD filespec  [,offset] 


Remarks:  filespec 


is  a  string  expression  for  the  file 
specification.  It  must  conform  to  the  rules 
outlined  under  "Naming  Files"  in  Chapter 
3,  otherwise  a  "Bad  file  name"  error  occurs 
and  the  load  is  cancelled. 


offset        is  a  numeric  expression  in  the  range  0  to 
65535.  This  is  the  address  at  which  loading 
is  to  start,  specified  as  an  offset  into  the 
segment  declared  by  the  last  DEF  SEG 
statement. 

If  offset  is  omitted,  the  offset  specified  at  BSAVE  is 
assumed.  That  is,  the  file  is  loaded  into  the  same 
location  it  was  saved  from. 


When  a  BLOAD  command  is  executed,  the  named 
file  is  loaded  into  memory  starting  at  the  specified 
location.  If  the  file  is  to  be  loaded  from  the  device 
CAS1:,  the  cassette  motor  is  turned  on 
automatically. 

If  you  are  using  Cassette  BASIC  and  the  device 
named  is  omitted,  CASl:  is  assumed.  CASl:  is  the 
only  allowable  device  for  BLOAD  in  Cassette 
BASIC.  If  you  are  using  Disk  or  Advanced  BASIC 
and  the  device  name  is  omitted,  the  DOS  default 
diskette  drive  is  used. 
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BLOAD 
Command 


BLOAD  and  BSAVE  are  useful  for  loading  and 
saving  machine  language  programs,  (You  may 
perform  machine  language  programs  from  within  a 
BASIC  program  by  using  the  CALL  statement.) 
However,  BLOAD  and  BSAVE  are  not  restricted  to 
machine  language  programs.  Any  segment  may  be 
specified  as  the  target  or  source  for  these  statements 
via  the  DEF  SEG  statement.  You  have  a  useful  way  of 
saving  and  displaying  screen  images:  save  from  or 
load  to  the  screen  buffer. 

Warning: 

BASIC  does  not  do  any  checking  on  the  address. 
That  is,  it  is  possible  to  BLOAD  anywhere  in 
memory.  You  should  not  BLOAD  over  BASIC'S 
stack,  BASIC'S  variable  area,  or  your  BASIC 
program. 

Notes  when  using  CASl: 

1.     If  you  enter  the  BLOAD  command  in  direct 
mode,  the  file  names  on  the  tape  will  be 
displayed  on  the  screen  followed  by  a  period  (.) 
and  a  single  letter  indicating  the  type  of  file. 
This  is  followed  by  the  message  "Skipped."  for 
the  files  not  matching  the  named  file,  and 
"Found."  when  the  named  file  is  found.  Types 
of  files  and  the  associated  letter  are: 

.B    for  BASIC  programs  in  internal  format 
(created  with  SAVE  command) 

.P     for  protected  BASIC  programs  in  internal 
format  (created  with  SAVE  ,P  command) 

.A    for  BASIC  programs  in  ASCII  format 
(created  with  SAVE  ,A  command) 

.M    for  memory  image  files  (created  with 
BSAVE  command) 

.D    for  data  files  (created  by  OPEN  followed  by 
output  statements) 
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BLOAD 
Command 


If  the  BLOAD  command  is  executed  in  a  BASIC 
program,  the  file  names  skipped  and  found  are 
not  displayed  on  the  screen. 

2.  You  may  press  Ctrl-Break  any  time  during 
BLOAD.  This  will  cause  BASIC  to  exit  the 
search  and  return  to  direct  mode  between  files 
or  after  a  time-out  period.  Previous  memory 
contents  do  not  change. 

3.  If  CASl:  is  specified  as  the  device  and  the 
filename  is  omitted,  the  next  memory  image 
(.M)  file  on  the  tape  is  loaded. 


Example: 


10  1  i    .if1    l.  nt'    ->c  i'rrr    M. i't-r 

2  0  '  p.  ■  i  n  !    SEG  .it    m  rtv:   Mil  i  et 

50  OFT   stG--    -.MB 801* 

■;+0  'if'  id   P  I  CTURt    i  n  !  f  :  rut"  1e  r 

S0  BlOmD  !|p  !  CUjRl"  ,0  I 

This  example  loads  the  screen  buffer  for  the 
Color/Graphics  Monitor  Adapter,  which  is  at 
absolute  address  hex  B8000.  If  you  were  loading  the 
screen  buffer  for  the  IBM  Monochrome  Display  and 
Parallel  Printer  Adapter,  you  would  have  to  change 
line  30  to  read  &HB000  (the  actual  address  is  hex  | 
B0000).  Note  that  the  DEF  SEG  statement  in  30  and 
the  offset  of  0  in  50  is  wise.  This  assures  that  the 
correct  address  is  used. 

The  example  for  BSAVE  in  the  next  section 
illustrates  how  PICTURE  was  saved. 
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BSAVE 
Command 


Purpose:     Saves  portions  of  the  computer's  memory  on  the 
specified  device. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      BSA  VEfilespec,  offset,  length 


Remarks:  filespec 


offset 


length 


is  a  string  expression  for  the  file 
specification.  It  must  conform  to  the  rules 
outlined  under  "Naming  Files"  in  Chapter 
3;  otherwise,  a  "Bad  file  name"  error 
occurs  and  the  save  is  cancelled. 

is  a  numeric  expression  in  the  range  0  to 
65  5  35-  This  is  the  offset  into  the  segment 
declared  by  the  last  DEF  SEG.  Saving  will 
start  from  this  position. 

is  a  numeric  expression  in  the  range  1  to 
65535.  This  is  the  length  of  the  memory 
image  to  be  saved. 


If  offset  or  length  is  omitted,  a  "Syntax  error"  will 
occur  and  the  save  will  be  cancelled. 

If  the  device  name  is  omitted  in  Cassette  BASIC, 
CASl :  is  assumed.  CASl :  is  the  only  allowable  device 
for  BSAVE  in  Cassette  BASIC.  In  Disk  and  Advanced 
BASIC,  if  the  device  name  is  omitted,  the  DOS 
default  diskette  drive  is  used. 

If  you  are  saving  the  CASl:,  the  cassette  motor  will 
be  turned  on  and  the  memory  image  file  will  be 
immediately  written  to  the  tape. 
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BSAVE 
Command 


BLOAD  and  BSAVE  are  useful  for  loading  and 
saving  machine  language  programs  (which  can  be 
called  using  the  CALL  statement).  However, 
BLOAD  and  BSAVE  are  not  restricted  to  machine 
language  programs.  By  using  the  DEF  SEG 
statement,  any  segment  may  be  specified  as  the 
target  or  source  for  these  statements.  For  example, 
you  can  save  an  image  of  the  screen  by  doing  a 
BSAVE  of  the  screen  buffer. 


Example: 


As  explained  under  "BLOAD  Command"  in  the 
previous  section,  the  address  of  the  16K  screen 
buffer  for  the  Color/Graphics  Monitor  Adapter  is 
hex  BSOOO.  The  address  of  the  4K  screen  buffer  fori 
the  IBM  Monochrome  Display  and  Parallel  Printer 
Adapter  is  hex  B0000. 


The  DEF  SEG  statement  must  be  used  to  set  up  the 
segment  address  to  the  start  of  the  screen  buffer. 
Offset  of  0  and  length  &H4000  specifies  that  the 
entire  16K  screen  buffer  is  to  be  saved. 
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CALL 
Statement 


Purpose:     Calls  a  machine  language  subroutine. 


Versions:    Cassette      Disk      Advanced  Compiler 


(**) 


Format:      CALL  numvar  {  {variable  [,variable]...)} 


Remarks: 


numvar 


varia 


:able 


is  the  name  of  a  numeric  variable.  The 
value  of  the  variable  indicates  the  starting 
memory  address  of  the  subroutine  being 
called  as  an  offset  into  the  current  segment 
of  memory  (as  defined  by  the  last  DEF  SEG 
statement). 

is  the  name  of  a  variable  which  is  to  be 
passed  as  an  argument  to  the  machine 
language  subroutine. 


The  CALL  statement  is  one  way  of  interfacing 
machine  language  programs  with  BASIC.  The  other 
way  is  by  using  the  USR  function.  Refer  to 
"Appendix  C.  Machine  Language  Subroutines"  for 
specific  considerations  about  using  machine 
language  subroutines. 


Example:   ] 00  Off  lfg=-,h8000 
']0  07-9 

120   CALL  0Z(A,B$,C; 

Line  1 00  sets  the  segment  to  location  hex  80000.  OZ 
is  set  to  zero  so  that  the  call  to  OZ  will  execute  the 
subroutine  at  location  hex  80000.  The  variables  A, 
B$,  and  C  are  passed  as  arguments  to  the  machine 
language  subroutine. 
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CDBL 
Function 


Purpose:     Converts  x  to  a  double-precision  number. 


Versions:    Cassette      Disk      Advanced  Compiler 

*  *  *  *  #  *  *  *  *  *  *  * 


Format:     v  =  CDBL<» 


Remarks:   x  may  be  any  numeric  expression. 

Rules  for  converting  from  one  numeric  precision  to 
another  are  followed  as  explained  in  "How  BASIC 
Converts  Numbers  from  One  Precision  to  Another" 
in  Chapter  3.  Refer  also  to  the  CINT  and  CSNG 
functions  for  converting  numbers  to  integer  and 
single-precision. 


Example:  ok 


1 0  A  -  .67 

20  PRINT  A. ;  C  D  B  L  '  A  1 
RUN 

^5't.6/  hbh  .66998/9  10  1  563 

Ok 


The  value  of  CDBL(A)  is  only  accurate  to  the  second 
decimal  place  after  rounding.  The  extra  digits  have 
no  meaning.  This  is  because  only  two  decimal  places 
of  accuracy  were  supplied  with  A. 
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CHAIN 
Statement 


Purpose:     Transfers  control  to  another  program,  and  passes 
variables  to  it  from  the  current  program. 

Versions:    Cassette      Disk      Advanced  Compiler 


Format:      CHAIN  [MERGE]  filespec  [,[line]  [,[ALL] 
[, DELETE  range]  ]  } 

Remarks:  filespec  follows  the  rules  for  file  specifications 
outlined  in  "Naming  Files"  in  Chapter  3.  The 
filename  is  the  name  of  the  program  that  is 
transferred  to.  Example: 


line  is  a  line  number  or  an  expression  that  evaluates 
to  a  line  number  in  the  chained-to  program.  It 
specifies  the  line  at  which  the  chained-to  program  is 
to  begin  running.  If  it  is  omitted,  execution  begins  at 
the  first  line  in  the  chained-to  program.  Example: 


line  (1000  in  this  example)  is  not  affected  by  a 
RENUM  command.  If  PROGl  is  renumbered,  this 
example  CHAIN  statement  should  be  changed  to 
point  to  the  new  line  number. 

ALL  specifies  that  every  variable  in  the  current 
program  is  to  be  passed  to  the  chained-to  program.  If 
the  ALL  option  is  omitted,  you  must  include  a 
COMMON  statement  in  the  chaining  program  to 
pass  variables  to  the  chained-to  program.  See 
"COMMON  Statement"  in  this  chapter.  Example: 
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CHAIN 
Statement 


MERGE  brings  a  section  of  code  into  the  BASIC 
program  as  an  overlay.  That  is,  a  MERGE  operation 
is  performed  with  the  chaining  program  and  the 
chained- to  program.  The  chained-to  program  must 
be  an  ASCII  file  if  it  is  to  be  merged.  Example; 


After  using  an  overlay,  you  will  usually  want  to 
delete  it  so  that  a  new  overlay  may  be  brought  in.  To 
do  this,  use  the  DELETE  option,  which  behaves  like 
the  DELETE  command.  As  in  the  DELETE 
command,  the  line  numbers  specified  as  the  first  and 
last  line  of  the  range  must  exist,  or  an  "Illegal 
function  call"  error  occurs.  Example: 


This  example  will  delete  lines  1000  through  5000  of 
the  chaining  program  before  loading  in  the  overlay 
(chained-to  program).  The  line  numbers  in  range  are 
affected  by  the  RENUM  command. 

Notes: 

1.  The  CHAIN  statement  leaves  files  open. 

2.  The  CHAIN  statement  with  MERGE  option 
preserves  the  current  OPTION  BASE  setting. 

3.  If  the  MERGE  option  is  omitted,  the  OPTION 
BASE  setting  is  not  preserved  in  the  chained-to 
program.  Also,  without  MERGE,  CHAIN  does 
not  preserve  variable  types  or  user-defined 
functions  for  use  by  the  chained-to  program. 
That  is,  any  DEFINT,  DEFSNG,  DEFDBL, 
DEFSTR,  or  DEF  FN  statements  containing 
shared  variables  must  be  restated  in  the  chained 
program. 
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CHR$ 
Function 


Purpose:     Converts  an  ASCII  code  to  its  character  equivalent. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:     v$  =  CHR$(tf) 


Remarks:   n  must  be  in  the  range  0  to  25  5. 

The  CHR$  function  returns  the  one-character  string 
with  ASCII  code  n.  (ASCII  codes  are  listed  in 
"Appendix  G.  ASCII  Character  Codes.")  CHR$  is 
commonly  used  to  send  a  special  character  to  the 
screen  or  printer.  For  instance,  the  BEL  character, 
which  beeps  the  speaker,  might  be  included  as 
CHR$(7)  as  a  preface  to  an  error  message  (instead  of 
using  BEEP).  Look  under  "ASC  Function,"  earlier  in 
this  chapter,  to  see  how  to  convert  a  character  back 
to  its  ASCII  code. 


Example:  0! 

PRINT   C  H  R  $  I  6  6 

B 

Ok 

The  next  example  sets  function  key  Fl  to  the  string 
"AUTO"  joined  with  Enter.  This  is  a  good  way  to  set 
the  function  keys  so  the  Enter  is  automatically  done 
for  you  when  you  press  the  function  key. 

Ok 

KFY    1  ,  "/\UT0"*-CHR$  !  1  3) 
Ok 
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CHR$ 
Function 


The  following  example  is  a  program  which  shows  all 
the  displayable  characters,  along  with  their  ASCII 
codes,  on  the  screen  in  80-column  width.  It  can  be 
used  with  either  the  IBM  Monochrome  Display  and 
Parallel  Printer  Adapter  or  the  Color/Graphics 
Monitor  Adapter. 

10  CLS 

20  FOR   1-1   TO  255 

30    1    ignore  noncl  i  s  p  1  nyab  I  e  characters 

;40   IF   (  I  :-6  AND    I  ■  \k)    OR    (  I    27  AN  D   I-  32  J   THEN    !  00 

50  COLOR  0,7    '   b 1 ack  on  oh  i  te 

60  PRINT  USING  j    .    i    3-digit   ASCII  oolo 

70  COLOR  7,0   '  whi le  on  black 
80  PR  I  NT   "         CM R $  i  I  )  ;    M  11 ; 

90   IF  POS(0)  -75  THEN  PRINT    '   qo  to  next  line 
100  NEXT  I 


> 
H 
tfl 

S 

tn 

HI 
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CINT 
Function 


Purpose:     Converts  x  to  an  integer. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:      v  =  CINT(x) 

Remarks:   x       may  be  any  numeric  expression.  If  x  is  not  in 
the  range  -32768  to  32767,  an  "Overflow" 
error  occurs. 

x  is  converted  to  an  integer  by  rounding  the 
fractional  portion. 

See  the  FIX  and  INT  functions,  both  of  which  also 
return  integers.  See  also  the  CDBL  and  CSNG 
functions  for  converting  numbers  to  single-  or 
double-precision. 

Example: 


Observe  in  both  examples  how  rounding  occurs. 
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CIRCLE 
Statement 


Purpose:    To  draw  an  ellipse  on  the  screen  with  center  (x, y)  and 
radius  r. 


Versions:    Cassette      Disk      Advanced  Compiler 


Graphics  mode  only. 


Format:      CIRCLE  {x,y),r  [.color  [,start,end  [,aspect]  ]  ] 


Remarks:  {x,y) 


color 


are  the  coordinates  of  the  center  of  the 
ellipse.  The  coordinates  may  be  given  in 
either  absolute  or  relative  form.  See 
"Specifying  Coordinates"  under 
"Graphics  Modes"  in  Chapter  3. 

is  the  radius  (major  axis)  of  the  ellipse  in  i 
points. 

is  a  number  which  specifies  the  color  of  the 
ellipse,  in  the  range  0  to  3-  In  medium 
resolution,  color  selects  the  color  from  the 
current  palette  as  defined  by  the  COLOR 
statement.  0  is  the  background  color.  The 
default  is  the  foreground  color,  color 
number  3.  In  high  resolution,  a  color  of  0 
(zero)  indicates  black,  and  the  default  of  1 
(one)  indicates  white. 


start,  end  are  angles  in  radians  and  may  range  from 
-2*PI  to  2*PI,  where  PI=3.141593. 


aspect 


is  a  numeric  expression. 
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CIRCLE 
Statement 


start  and  end  specify  where  the  drawing  of  the  ellipse 
will  begin  and  end.  The  angles  are  positioned  in  the 
standard  mathematical  way,  with  0  to  the  right  and 
going  counterclockwise: 


PI/2 


3*PI/2 


If  the  start  or  end  angle  is  negative  (-0  is  not  allowed), 
the  ellipse  will  be  connected  to  the  center  point  with 
a  line,  and  the  angles  will  be  treated  as  if  they  were 
positive  (note  that  this  is  not  the  same  as  adding 
2*PI).  The  start  angle  may  be  greater  or  less  than  the 
end  angle.  For  example, 

10  Pi-3.  1^1593 
20  SCREEN  1 

30   C ! RCLE    ' 1 60 ,  1 00 1  , 60  ,  , -P I  ,  - P I /2 
will  draw  a  part  of  a  circle  similar  to  the  following: 


aspect  affects  the  ratio  of  the  x-  radius  to  the  y- radius. 
The  default  for  aspect  is  5/6  in  medium  resolution  and 
5/12  in  high  resolution.  These  values  give  a  visual 
circle  assuming  the  standard  screen  aspect  ratio  of 
4/3. 
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CIRCLE 
Statement 


If  aspect  is  less  than  one,  then  r  is  the  x- radius.  That  is, 
the  radius  is  measured  in  points  in  the  horizontal 
direction.  If  aspect  is  greater  than  one,  then  r  is  the 
y-radius.  For  example, 

10  SCREEN  1 

20  CIRCLE    M60,  100!  ,60,  ,  ,  ,5/18 
will  draw  an  ellipse  like  this: 


In  many  cases,  an  aspect  of  1  (one)  will  give  nicer 
looking  circles  in  medium  resolution.  This  will  also 
cause  the  circle  to  be  drawn  somewhat  faster. 

The  last  point  referenced  after  a  circle  is  drawn  is  the 
center  of  the  circle. 

Points  that  are  off  the  screen  are  not  drawn  bv 
CIRCLE. 


Example:    The  following  example  draws  a  face. 

10  P  i  ---  \ .  1  ''-i  i  5  9  3 

20   SCRt  EN    1    1   i-vd  i  u.-i  re*  .  qrophics 

30   COLOR  0,!    1    block  b-ickq  round  ,   pnloi  W- 

/ 0    1  L:v    c  i  i'l  I  es    i  n  c i  -  j      1    (  cvdiii 

50  CIRCLE    (  120,50*  ,10.  ! 

60   C  I  RCLE    <  200  ,50)  ,10,1 

70    '  t '..'•<  hor  i  zi.n  t  ,i  1    e  1  1  i  p\e'- 

80   CIRCLE    t  120, 50'  ,30,  , ,  ,5/18 

00  C  IRC.E   '  200,50.'  .  30,  .  ,  ,5/18 

100    On',    if  L'-  >  to  r  2   1  -njcjen '  1 

110  C  I  R  ;LE   i  160  ,0   ,  !  50  ,?  ,    1  .  3  P  I  ,    1  .  7  0-  ! 

120    0")i"i.  ,   oiH'  side  cmnecied    In  center 

130  CIRCLE   !  160,52!  ,50,  ,    1  . V  P !  ,  -1.6"PI 
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CLEAR 
Command 


Purpose:     Sets  all  numeric  variables  to  zero  and  all  string 

variables  to  null.  Options  set  the  end  of  memory  and 
the  amount  of  stack  space. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format: 


CLEAR  [,[»]  [,m]} 


Remarks:   n      is  a  byte  count  which,  if  specified,  sets  the 
maximum  number  of  bytes  for  the  BASIC 
workspace  (where  your  program  and  data  are 
stored,  along  with  the  interpreter  workarea). 
You  would  probably  include  n  if  you  need  to 
reserve  space  in  storage  for  machine  language 
programs. 


m  sets  aside  stack  space  for  BASIC.  The  default  is 
512  bytes,  or  one-eighth  of  the  available 
memory  (whichever  is  smaller).  You  may  want 
to  include  m  if  you  use  a  lot  of  nested  GOSUB 
statements  or  FOR.. .NEXT  loops  in  your 
program,  or  if  you  use  PAINT  to  do  complex 
scenes. 


CLEAR  frees  all  memory  used  for  data  without 
erasing  the  program  which  is  currently  in  memory. 
After  a  CLEAR,  arrays  are  undefined;  numeric 
variables  have  a  value  of  zero;  string  variables  have  a 
null  value;  and  any  information  set  with  any  DEF 
statement  is  lost.  (This  includes  DEF  FN,  DEF  SEG, 
and  DEF  USR,  as  well  as  DEFINT,  DEFDBL, 
DEFSNG,  and  DEFSTR.) 
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CLEAR 
Command 


Executing  a  CLEAR  command  turns  off  any  sound 
that  is  running  and  resets  to  Music  Foreground. 
Also,  PEN  and  STRIG  are  reset  to  OFF. 

The  ERASE  statement  may  be  useful  to  free  some 
memory  without  erasing  all  the  data  in  the  program. 
It  erases  only  specified  arrays  from  the  work  area. 
Refer  to  "ERASE  Statement"  in  this  chapter  for 
details. 


Example:   This  example  clears  all  data  from  memory  (without 
erasing  the  program): 


The  next  example  clears  the  data  and  sets  the 
maximum  workspace  size  to  32K-bytes: 


The  next  example  clears  the  data  and  sets  the  size  of  | 
the  stack  to  2000  bytes: 


The  last  example  clears  data,  sets  the  maximum 
workspace  for  BASIC  to  32K-bytes,  and  sets  the 
stack  size  to  2000  bytes: 
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CLOSE 
Statement 


Purpose:     Concludes  I/O  to  a  device  or  file. 

Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:      CLOSE  [[#]  filenum  [,[#]  filenum\...\ 

Remarks:  filenum     is  the  number  used  on  the  OPEN 
statement. 

The  association  between  a  particular  file  or  device 
and  its  file  number  stops  when  CLOSE  is  executed. 
Subsequent  I/O  operations  specifying  that  file 
number  will  be  invalid.  The  file  or  device  may  be 
opened  again  using  the  same  or  a  different  file 
number;  or  the  file  number  may  be  reused  to  open 
any  device  or  file. 

A  CLOSE  to  a  file  or  device  opened  for  sequential 
output  causes  the  final  buffer  to  be  written  to  the  file 
or  device. 

A  CLOSE  with  no  file  numbers  specified  causes  all 
devices  and  files  that  have  been  opened  to  be  closed. 

Executing  an  END,  NEW,  RESET,  SYSTEM  or 
RUN  without  the  R  option  causes  all  open  files  and 
devices  to  be  automatically  closed.  STOP  does  not 
close  any  files  or  devices. 

Refer  also  to  "OPEN  Statement"  in  this  chapter  for 
information  about  opening  files. 
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CLOSE 
Statement 


Example:    100  CLOSE  1  ,  '-2  ,  3 


Causes  the  files  and  devices  associated  with  file 
numbers  1,  2,  and  3  to  be  closed. 

200  C  LOS  F 

Causes  all  open  devices  and  files  to  be  closed. 
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CLS 

Statement 


Purpose:     Clears  the  screen. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:  CLS 


Remarks:   If  the  screen  is  in  text  mode,  the  active  page  (see 
"SCREEN  Statement"  in  this  chapter)  is  cleared  to 
the  background  color  (see  "COLOR  Statement," 
also  in  this  chapter). 


If  the  screen  is  in  graphics  mode  (medium  or  high 
resolution),  the  entire  screen  buffer  is  cleared  to  the 
background  color. 


The  CLS  statement  also  returns  the  cursor  to  the 
home  position.  In  text  mode,  this  means  the  cursor 
is  located  in  the  upper  left-hand  corner  of  the  screen. 
In  graphics  mode,  this  means  the  "last  referenced 
point"  for  future  graphics  statements  is  the  point  in 
the  center  of  the  screen  ((160,100)  in  medium 
resolution,  (320,100)  in  high  resolution). 


Changing  the  screen  mode  or  width  by  using  the 
SCREEN  or  WIDTH  statements  also  clears  the 
screen.  The  screen  may  also  be  cleared  by  pressing 
Ctrl-Home. 


Example: 
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With  the  Color/Graphics  Monitor  Adapter,  this 
example  clears  the  screen  to  Blue. 


COLOR 
Statement 


Purpose:  Sets  the  colors  for  the  foreground,  background,  and 
border  screen.  Refer  to  "Text  Mode"  in  Chapter  3 
for  an  explanation  of  these  terms. 

The  syntax  of  the  COLOR  statement  depends  on 
whether  you  are  in  text  mode  or  graphics  mode,  as 
set  by  the  SCREEN  statement. 

In  text  mode,  you  can  set  the  following: 

Foreground-  1  of  16  colors 

Character  blink,  if  desired 
Background-  1  of  8  colors 
Border-  1  of  16  colors 

You  can  set  the  following  in  medium  resolution 
graphics  mode: 

Background-  1  of  16  colors 
Palette-  1  of  2  palettes  with  3  colors  each 

The  border  is  the  same  as  the  background  color. 


The  COLOR  Statement  in  Text  Mode 

Versions:    Cassette      Disk      Advanced  Compiler 

*  #  $  *  *  *  *  *  *  *## 

Text  mode  only. 


Format:      COLOR  [foreground]  {.{background]  {, border]] 
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COLOR 

Statement  (Text) 


Remarks:  foreground     is  a  numeric  expression  in  the  range  0  to 

31,  representing  the  character  color. 

background   is  a  numeric  expression  in  the  range  0  to 
7  for  the  background  color. 

border  is  a  numeric  expression  in  the  range  0  to 

15.  It  is  the  color  for  the  border  screen. 

If  you  have  the  Color/Graphics  Monitor  Adapter, 

the  following  colors  are  allowed  for  foreground: 


0 

Black 

8 

Gray 

1 

Blue 

9 

Light  Blue 

2 

Green 

10 

Light  Green 

3 

Cyan 

11 

Light  Cyan 

4 

Red 

12 

Light  Red 

5 

Magenta 

13 

Light  Magenta 

6 

Brown 

14 

Yellow 

7 

White 

15 

High-intensity  White 

Colors  and  intensity  may  vary  depending  on  your 
display  device. 

You  might  like  to  think  of  colors  8  to  1 5  as  "light"  or 
"high-intensity"  values  of  colors  0  to  7. 

You  can  make  the  characters  blink  by  setting 
foreground  equal  to  16  plus  the  number  of  the  desired 
color.  That  is,  a  value  of  16  to  31  causes  blinking 
characters. 

You  may  select  only  colors  0  through  7  for 
background. 
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COLOR 
Statement  (Text) 


If  you  have  the  IBM  Monochrome  Display  and 
Parallel  Printer  Adapter,  the  following  values  can 
be  used  for  foreground: 

0  Black 

1  Underlined  character  with  white  foreground 
2-7  White 

In  a  manner  similar  to  the  Color/Graphics  Monitor 
Adapter,  adding  8  to  the  number  of  the  desired  color 
gives  you  the  color  in  high-intensity.  For  example,  a 
value  of  1 5  gives  you  high-intensity  white,  A  value  of 
9  gives  you  high-intensity  white,  underlined.  You 
can't  make  high-intensity  black. 

As  with  the  Color/Graphics  Monitor  Adapter,  you 
can  make  the  character  blink  by  adding  16  to  the 
number  of  the  desired  color.  Thus,  16  gives  you 
black  blinking  characters,  and  31  gives  you 
high-intensity  white  blinking  characters. 

For  background  with  the  IBM  Monochrome  Display 
and  Parallel  Printer  Adapter,  you  may  select  the 
following  values: 

0-6  Black 
7  White 

Note:    White  (color  7)  as  a  background  color 
shows  up  as  white  on  the  IBM  Monochrome 
Display  only  when  it  is  used  with  a  foreground 
color  of  0,  8,  16,  or  24  (black).  This  creates 
reverse  image  characters. 

Black  (color  0,  8,  16,  or  24)  as  a  foreground 
color  shows  up  as  black  only  when  used  with  a 
background  color  of  0  (which  makes  the 
characters  invisible)  or  7  (which  creates  reverse 
image  characters). 

Other  combinations  of  foreground  and 
background  colors  produce  standard  (white  on 
black)  results  on  the  IBM  Monochrome 
Display. 
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COLOR 

Statement  (Text) 

Notes  for  either  adapter: 

1 .  Foreground  color  may  equal  background  color. 
This  has  the  effect  of  making  any  character 
displayed  invisible.  Changing  the  foreground  or 
background  color  will  make  subsequent 
characters  visible  again. 

2.  Any  parameter  may  be  omitted.  Omitted 
parameters  assume  the  old  value. 

3.  If  the  COLOR  statement  ends  in  a  comma  (,), 
you  will  get  a  "Missing  operand"  error,  but  the 
color  will  change.  For  example, 

COLOR  ,7, 

is  invalid. 

4.  Any  values  entered  outside  the  range  0  to  255 
will  result  in  an  "Illegal  function  call"  error. 
Previous  values  are  retained. 


Example: 


This  sets  a  yellow  foreground,  a  blue  background, 
and  a  black  border  screen. 
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COLOR 
Statement  (Text) 


The  following  example  can  be  used  with  either  the 
Color/Graphics  Monitor  Adapter  or  the  IBM 
Monochrome  Display  and  Parallel  Printer  Adapter: 

10  PRINT   'Enter  your  "; 

20  COLOR   15,0    'hignl  ight  ne;  ...rd 

30  PRINT  "pdbsword"; 

bfi  COLOR  7  'return  to  default  (white  on  black) 
50  PRINT    1  nere. 

60  COLOR  0         ' invisible    (Clack  en  black 
70   INpUT  PASSWORDS 
80   i  F  PASSWORD$  =  "sec-et  1  THEN   1 20 
30    '    blink  and  highlight   errjr  message 
00  COLOR  31     PRINT  "Wrong  Password11;   COLOR  / 
1  i0  GOTO  10 

120  COLOR  0./     'reverse   image   (black  :>•->  wh"  te  l 
130  PRINT   "Program  continues.  "; 

140  COLOR  7,0     'return   ,      default    'white  on  black) 


C/5 

H 

> 

m 

tn 
Z 

H 

on 
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COLOR 

Statement  (Graphics) 

The  COLOR  Statement  in  Graphics  Mode 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 

Graphics  mode,  medium  resolution  only. 

Format:      COLOR  [background]  [,{palette]] 

Remarks:   background  is  a  numeric  expression  specifying  the 

background  color.  The  colors  allowed 
for  background  are  0  through  15,  as 
described  previously  under  "The 
COLOR  Statement'in  Text  Mode." 

palette         is  a  numeric  expression  which  selects  the 
palette  of  colors. 

The  colors  selected  when  you  choose  each  palette 
are  as  follows: 


Color  Palette  0  Palette  1 

1  Green  Cyan 

2  Red  Magenta 

3  Brown  White 

If palette  is  an  even  number,  palette  0  is  selected.  This 
associates  the  colors  Green,  Red,  and  Brown  to  the 
color  numbers  1,  2,  and  3.  Palette  1 
(Cyan/Magenta/White)  is  selected  when  palette  is  an 
odd  number. 

The  color  selected  for  background  may  be  the  same  as 
any  of  the  palette  colors. 
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COLOR 
Statement  (Graphics) 


Any  parameter  may  be  omitted  from  the  COLOR 
statement.  Omitted  parameters  assume  the  old 
value. 

In  graphics  mode,  the  COLOR  statement  sets  a 
background  color  and  a  palette  of  three  colors.  You 
may  select  any  one  of  these  four  colors  for  display 
with  the  PSET,  PRESET,  LINE,  CIRCLE,  PAINT, 
and  DRAW  statements.  It  has  meaning  in  medium 
resolution  only  (set  by  SCREEN  1  statement).  Using 
COLOR  in  high  resolution  will  result  in  an  "Illegal 
function  call"  error. 

Any  values  entered  outside  the  range  0  to  255  will 
result  in  an  "Illegal  function  call"  error.  Previous 
values  will  be  retained. 


Example:    5  SCREEN  1 

10  COLOR  9,0 


Sets  the  background  to  light  blue,  and  selects  palette 
0. 

20  CO. OR   ,  1 


The  background  stays  light  blue,  and  palette  1  is 
selected. 
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COM(n) 
Statement 


Purpose:     Enables  or  disables  trapping  of  communications 
activity  to  the  specified  communications  adapter. 

Versions:    Cassette      Disk      Advanced  Compiler 

/**\ 

Format:      COM(«)  ON 
COM(ff)  OFF 
COM(«)  STOP 

Remarks:   n       is  the  number  of  the  communications  adapter 
(1  or  2). 

A  COM(»)  ON  statement  must  be  executed  to  allow 
trapping  by  the  ON  COM(«)  statement.  After 
COM(tf)  ON,  if  a  non-zero  line  number  is  specified  in 
the  ON  COM(»)  statement,  BASIC  checks  to  see  if 
any  characters  have  come  in  to  the  communications 
adapter  every  time  a  new  statement  is  executed. 

If  COM(tf)  is  OFF,  no  trapping  takes  place  and  any 
communication  activity  is  not  remembered  even  if  it 
does  take  place. 

If  a  COM(#)  STOP  statement  has  been  executed,  no 
trapping  can  take  place.  However,  any 
communications  activity  that  does  take  place  is 
remembered  so  that  an  immediate  trap  occurs  when 
COM(tf)  ON  is  executed. 
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COMMON 
Statement 


Purpose:     Passes  variables  to  a  chained  program. 


Versions:    Cassette     Disk      Advanced  Compiler 

***  ***  (**) 


Format:      COMMON  variable[,variable}. 


Remarks:  variable 


is  the  name  of  a  variable  that  is  to  be  passed 
to  the  chained-to  program.  Array  variables 
are  specified  by  appending  "( )"  to  the 
variable  name. 


The  COMMON  statement  is  used  in  conjunction 
with  the  CHAIN  statement.  COMMON  statements 
may  appear  anywhere  in  a  program,  although  it  is 
recommended  that  they  appear  at  the  beginning. 
Any  number  of  COMMON  statements  may  appear  in 
a  program,  but  the  same  variable  cannot  appear  in 
more  than  one  COMMON  statement.  If  all  variables 
are  to  be  passed,  use  CHAIN  with  the  ALL  option 
and  omit  the  COMMON  statement. 

Any  arrays  that  are  passed  do  not  need  to  be 
dimensioned  in  the  chained-to  program. 


Example: 


This  examp'e  chains  to  program  PROG3  on  the 
diskette  in  drive  A:,  and  passes  the  array  D  along  with 
the  variables  A,  BEE1,  C,  and  G$. 
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CONT 
Command 


Purpose:     Resumes  program  execution  after  a  break. 

Versions:    Cassette      Disk      Advanced  Compiler 
**  *  **  *  *** 


Format:  CONT 


Remarks:   The  CONT  command  may  be  used  to  resume 
program  execution  after  Ctrl-Break  has  been 
pressed,  a  STOP  or  END  statement  has  been 
executed,  or  an  error  has  occurred.  Execution 
continues  at  the  point  where  the  break  happened.  If 
the  break  occurred  after  a  prompt  from  an  INPUT 
statement,  execution  continues  with  the  reprinting 
of  the  prompt. 

CONT  is  usually  used  in  conjunction  with  STOP  for 
debugging.  When  execution  is  stopped,  you  can 
examine  or  change  the  values  of  variables  using 
direct  mode  statements.  You  may  then  use  CONT  to 
resume  execution,  or  you  may  use  a  direct  mode 
GOTO,  which  resumes  execution  at  a  particular  line 
number. 

CONT  is  invalid  if  the  program  has  been  edited 
during  the  break. 
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CONT 
Command 


Example:    In  the  following  example,  we  create  a  long  loop. 

Ok 

10  FOR  A=l   TO  50 
20  PRI NT  A; 
30  NEXT  A 
RUN 

123^56789     10     11  12 
13     1*+     15     16     17     18     19     20     21  22 
23     2k     25     26     27     28  29 

(At  this  point  we  interrupt  the  loop  by  pressing 
Ctrl-Break.) 


Break  in  20 
Ok 

CONT 

30  31 

k$     h  1 

50 
Ok 


32  33  3^  35  .36  37  38  39 
/+2    ^3    ^    45    ^6    ^7    ^8  ^9 
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COS 

Function 


Purpose:     Returns  the  trigonometric  cosine  function. 

Versions:    Cassette       Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:      v  =  COS(.r) 

Remarks:  x    is  the  angle  whose  cosine  is  to  be  calculated.  The 
value  of  x  must  be  in  radians.  To  convert  from 
degrees  to  radians,  multiply  the  degrees  by 
PI/180,  where  PI=3. 141593. 

The  calculation  of  COS(x)  is  performed  in  single 

Di  CC  lol  Oil. 

Example:  Qj 

10  PI -3.  1  '4 1  59 3 

20  PRINT  COS  IP  I  ) 

30  DEGRE  ES  =  1 80 

^40  RAO  I  ANS=DEG  RE  E  S  P  t  /  1  80 

50  PRINT  COS (RADIANS) 

RUN 

-1 

-  I 

Ok 

This  example  shows,  first,  that  the  cosine  of  PI 
radians  is  equal  to  -1 .  Then  it  calculates  the  cosine  of 
180  degrees  by  first  converting  the  degrees  to 
radians  (180  degrees  happens  to  be  the  same  as  PI 
radians). 


CSNG 
Function 


Purpose:     Converts  .r  to  a  single-precision  number. 
Versions:    Cassette     Disk      Advanced  Compiler 


4e  +  *  *  *  * 


Format:     v  =  CSNG(.r) 


Remarks:   x    is  a  numeric  expression  which  will  be  converted 
to  single-precision. 

The  rules  outlined  under  "How  BASIC  Converts 
Numbers  from  One  Precision  to  Another"  in 
Chapter  3  are  used  for  the  conversion. 

See  the  CINT  and  CDBL  functions  for  converting 
numbers  to  the  integer  and  double-precision  data 
types. 


Example:  Ok 

10  A----  -  975  .  3^2  I  222  • 
20  PRINT  A--;    CSNG  ( A  ^  » 
RUN 

97  5.  3'* 2  122 2     975. 3^21 

Ok 

The  value  of  the  double-precision  number  A#  is 
rounded  at  the  seventh  digit  and  returned  as 
CSNG(A#). 
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CSRLIN 
Variable 


Purpose:  Returns  the  vertical  coordinate  of  the  cursor. 
Versions:    Cassette      Disk      Advanced  Compiler 


Format:     v  =  CSRLIN 


Remarks:   The  CSRLIN  variable  returns  the  current  line  (row) 
position  of  the  cursor  on  the  active  page.  (The  active 
page  is  explained  under  "SCREEN  Statement"  in 
this  chapter.)  The  value  returned  will  be  in  the  range 
1  to  25. 

The  POS  function  returns  the  column  location  of 
the  cursor.  Refer  to  "POS  Function"  in  this  chapter. 

Refer  to  "LOCATE  Statement"  to  see  how  to  set  the 
cursor  line. 

Example:    10  Y  --  CSRLIN     '  rea"-,i  oir  rent    I  i  ne 

20   X  -  POS (0 )      '  record   current    c-i  ucn 
25    '  pi'  irr    HI    MOM  on    I  i  nt   2  k 
30   LOCATr   2k  , ! :    PR ! NT   "H I  MOM" 
LOCATT   Y  ,X      '  ic-ctiire  pes  it  inn 

This  example  saves  the  cursor  coordinates  in  the 
variables  X  and  Y,  then  moves  the  cursor  to  line  24 
to  put  the  words  "HI  MOM"  on  that  line.  Then  the 
cursor  is  moved  back  to  its  old  position. 
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CVI,  CVS,  CVD 
Functions 


Purpose:     Converts  string  variable  types  to  numeric  variable 
types. 


Versions:  Cassette 


Disk 
*  *  * 


Advanced 
*  *  * 


C 


ompiler 
*** 


Format:  v  =  CVl(2-byte  string) 
v  =  CVS(4-byte  string) 
v  =  CVD(8-byte  string) 


Remarks:    Numeric  values  that  are  read  from  a  random  file 

must  be  converted  from  strings  into  numbers.  CVI 
converts  a  two-byte  string  to  an  integer.  CVS 
converts  a  four-byte  string  to  a  single-precision 
number.  CVD  converts  an  eight-byte  string  to  a 
double-precision  number. 

The  CVI,  CVS,  and  CVD  functions  do  not  change  the 
bytes  of  the  actual  data.  They  only  change  the  way 
BASIC  interprets  those  bytes. 

See  also  "MKI$,  MKS$,  MKD$  Functions"  in  this 
chapter,  and  "Appendix  B.  BASIC  Diskette  Input 
and  Output." 


Example:   70  FIELD  #1,4  AS  N$,    12  AS  B$ 

80  GET  si 
90  Y=CVS(NS) 


This  example  uses  a  random  file  (#1)  which  has  fields 
defined  as  in  line  70.  Line  80  reads  a  record  from  the 
file.  Line  90  uses  the  CVS  function  to  interpret  the 
first  four  bytes  (N$)  of  the  record  as  a 
single-precision  number.  N$  was  probably  originally 
a  number  which  was  written  to  the  file  using  the 
MKS$  function. 
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DATA 
Statement 


Purpose:     Stores  the  numeric  and  string  constants  that  are 
accessed  by  the  program's  READ  statement(s). 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      DATA  constant\,constant\.. 


Remarks:   constant    may  be  a  numeric  or  string  constant.  No 
expressions  are  allowed  in  the  list.  The 
numeric  constants  may  be  in  any  format  — 
integer,  fixed  point,  floating  point,  hex,  or 
octal.  String  constants  in  DATA 
statements  do  not  need  to  be  surrounded 
by  quotation  marks,  unless  the  string 
contains  commas,  colons,  or  significant 
leading  or  trailing  blanks. 

DATA  statements  are  nonexecutable  and  may  be 
placed  anywhere  in  the  program.  A  DATA  statement 
may  contain  as  many  constants  as  will  fit  on  a  line, 
and  any  number  of  DATA  statements  may  be  used  in 
a  program.  The  information  contained  in  the  DATA 
statements  may  be  thought  of  as  one  continuous  list 
of  items,  regardless  of  how  many  items  are  on  a  line 
or  where  the  lines  are  placed  in  the  program.  The 
READ  statements  access  the  DATA  statements  in 
line  number  order. 
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DATA 
Statement 


The  variable  type  (numeric  or  string)  given  in  the 
READ  statement  must  agree  with  the  corresponding 
constant  in  the  DATA  statement  or  a  "Syntax  error" 
occurs. 

You  can  use  the  RESTORE  statement  to  reread 
information  from  any  line  in  the  list  of  DATA 
statements.  (See  "RESTORE  Statement"  in  this 
chapter.) 


Example:    See  examples  under  "READ  Statement"  in  this 
chapter. 


C/5 

> 

H 
m 

m 

H 

C/5 
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DATE$ 

Variable  and  Statement 


Purpose:     Sets  or  retrieves  the  date. 

Versions:    Cassette      Disk      Advanced  Compiler 

*  *  *  *  *  * 


Format:      As  a  variable: 
v$  =  DATE$ 
As  a  statement: 
DATE$  =  x$ 

Remarks:   For  the  variable  (v$  =  DATE$): 

A  10-character  string  of  the  form  mm-dd-yyyy  is 
returned.  Here,  mm  represents  two  digits  for  the 
month,  dd  is  the  day  of  the  month  (also  2  digits),  and 
yyyy  is  the  year.  The  date  may  have  been  set  by  DOS 
prior  to  entering  BASIC. 

For  the  statement  (DATE$  =  x$): 

x$  is  a  string  expression  which  is  used  to  set  the 
current  date.  You  may  enter  x$  in  any  one  of  the 
following  forms: 

mm-dd-yy 
mm/dd/yy 
mm-dd-yyyy 
mm/dd/yyyy 

The  year  must  be  in  the  range  1980  to  2099-  If  you 
use  only  one  digit  for  the  month  or  day,  a  0  (zero)  is 
assumed  in  front  of  it.  If  you  give  only  one  digit  for 
the  year,  a  2ero  is  appended  to  make  it  two  digits.  If 
you  give  only  two  digits  for  the  year,  the  year  is 
assumed  to  be  \9yy. 
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DATE$ 

Variable  and  Statement 


Example:  Ok 

10  DAT E $=  "8/29/82" 
20  PRINT  DATE$ 
RUN 

08-29-1982 

Ok 

In  the  example  we  set  the  date  to  August  29th,  1982. 
Notice  how,  when  we  read  the  date  back  using  the 
DATE$  function,  a  zero  was  included  in  front  of  the 
month  to  make  it  two  digits,  and  the  year  became 
1982.  Also,  the  month,  day,  and  year  are  separated 
by  hyphens  even  though  we  entered  them  as  slashes. 

Note:  DATES  operates  in  U.S.  format  (mm-dd-yy). 


in 
H 
> 

m 

£ 

m 

Z 
H 

C/5 
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DEF  FN 
Statement 


Purpose:     Defines  and  names  a  function  that  you  write. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      DEF  ¥Nname[(arg  [,arg]..,)}  =expression 


Remarks:   name        is  a  valid  variable  name.  This  name, 

preceded  by  FN,  becomes  the  name  of  the 
function. 

arg  is  an  argument.  It  is  a  variable  name  in  the 

function  definition  that  will  be  replaced 
with  a  value  when  the  function  is  called. 
The  arguments  in  the  list  represent,  on  a 
one-to-one  basis,  the  values  that  are  given 
when  the  function  is  called. 

expression  defines  the  returned  value  of  the  function. 
The  type  of  the  expression  (numeric  or 
string)  must  match  the  type  declared  by 
name. 

The  definition  of  the  function  is  limited  to  one 
statement.  Arguments  {arg)  that  appear  in  the 
function  definition  serve  only  to  define  the  function; 
they  do  not  affect  program  variables  that  have  the 
same  name.  A  variable  name  used  in  the  expression 
does  not  have  to  appear  in  the  list  of  arguments.  If  it 
does,  the  value  of  the  argument  is  supplied  when  the 
function  is  called.  Otherwise,  the  current  value  of 
the  variable  is  used. 
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DEF  FN 
Statement 


Example: 


The  function  type  determines  whether  the  function 
returns  a  numeric  or  string  value.  The  type  of  the 
function  is  declared  by  name,  in  the  same  way  as 
variables  are  declared  (see  "How  to  Declare  Variable 
Types"  in  Chapter  3).  If  the  type  of  expression  (string 
or  numeric)  does  not  match  the  function  type,  a 
"Type  mismatch"  error  occurs.  If  the  function  is 
numeric,  the  value  of  the  expression  is  converted  to 
the  precision  specified  by  name  before  it  is  returned 
to  the  calling  statement. 

A  DEF  FN  statement  must  be  executed  to  define  a 
function  before  you  may  call  that  function.  If  a 
function  is  called  before  it  has  been  defined,  an 
"Undefined  user  function"  error  occurs.  On  the 
other  hand,  a  function  may  be  defined  more  than 
once.  The  most  recently  executed  definition  is  used. 

Note:  You  may  have  a  recursive  function,  that 
is,  one  which  calls  itself.  However,  if  you  don't 
provide  a  way  to  stop  the  recursion,  an  "Out  of 
memory"  error  occurs. 

DEF  FN  is  invalid  in  direct  mode. 


Ok 

10  F  !     3.  .  1  U  1  fjCl  i 

20  DLT   TNaR!-/,  ;  K  ■  -P  I    R  2 

30  !  NPl.T    1 R , ,  ■  •  i  ■ , : ■  :   ■ 1  ,  R --\  D  I 

-t?  PRIM    "A.  <   ■    i  rrj.,R[ 


(Suppose  you  respond  with  2.) 


Ok 
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DEF  FN 
Statement 


Line  20  defines  the  function  FNAREA,  which 
calculates  the  area  of  a  circle  with  radius  R.  The 
function  is  called  in  line  40. 

Here  is  an  example  with  two  arguments: 

Ok 

10   DLF   FNMUD*  X  ,  Y) -X- i  INTiX/Y)    Y  i 
20  A  -   FNMUD  (  7  •  ^  ,y+  1 
30  PRINT  A 
RUN 

Ok 
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DEF  SEG 
Statement 


Purpose:     Defines  the  current  "segment"  of  storage.  A 

subsequent  BLOAD,  BSAVE,  CALL,  PEEK,  POKE, 
or  USR  definition  will  define  the  actual  physical 
address  of  its  operation  as  an  offset  into  this 
segment. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      DEF  SEG  [^address] 


Remarks:   address  is  a  numeric  expression  in  the  range  0  to 
65535. 

The  initial  setting  for  the  segment  when  BASIC  is 
started  is  BASIC s  Data  Segment  (DS).  BASIC s  Data 
Segment  is  the  beginning  of  your  user  workspace  in 
memory.  If  you  execute  a  DEF  SEG  statement  which 
changes  the  segment,  the  value  does  not  get  reset  to 
BASICs  DS  when  you  issue  a  RUN  command. 

If  address  is  omitted  from  the  DEF  SEG  statement, 
the  segment  is  set  to  BASICs  Data  Segment. 

Kaddress  is  given,  it  should  be  a  value  based  upon  a  16 
byte  boundary.  The  value  is  shifted  left  4  bits 
(multiplied  by  16)  to  form  the  segment  address  for 
the  subsequent  operation.  That  is,  if  address  is  in 
hexadecimal,  a  0  (zero)  is  added  to  get  the  actual 
segment  address.  BASIC  does  not  perform  any 
checking  to  assure  that  the  segment  value  is  valid. 
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DEF  SEG 
Statement 


DEF  and  SEG  must  be  separated  by  a  space. 
Otherwise,  BASIC  will  interpret  the  statement 
DEFSEG=100  to  mean:  "assign  the  value  100  to  the 
variable  DEFSEG." 

Any  value  entered  outside  the  range  indicated  will 
result  in  an  "Illegal  function  call"  error.  The 
previous  value  will  be  retained. 

Refer  to  "Appendix  C.  Machine  Language 
Subroutines"  for  more  information  on  using 
DEF  SEG. 


Example:    1 00  dff  srs  1   !-,.- .  v.i   ;>■  B,".sh,  OS 

203    1    sel    '-, eymen  '    (u  <._•>'.<,!    -,<.:  t'c  bu*"U'! 
2  10   DF  P  :^FG-SHB800 

In  the  second  example,  the  screen  buffer  for  the 
Color/Graphics  Monitor  adapter  is  at  absolute 
address  B8000  hex.  Since  segments  are  specified  on 
16  byte  boundaries,  the  last  hex  digit  is  dropped  on 
the  DEF  SEG  specification. 
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DEFtype 
Statements 


Purpose:     Declares  variable  types  as  integer,  single-precision, 
double-precision,  or  string. 


Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  *** 


Format:      DEFtype  letter\-letter\  [Jetter  [-/etter]]... 

Remarks:  type         is  INT,  SNG,  DBL,  or  STR. 

letter        is  a  letter  of  the  alphabet  (A-Z). 

A  DEFtype  statement  declares  that  the  variable 
names  beginning  with  the  letter  or  letters  specified 
will  be  that  type  of  variable.  However,  a  type 
declaration  character  (%,  !,  #,  or  $)  always  takes 
precedence  over  a  DEFtype  statement  in  the  typing 
of  a  variable.  Refer  to  "How  to  Declare  Variable 
Types"  in  Chapter  3. 

If  no  type  declaration  statements  are  encountered, 
BASIC  assumes  that  all  variables  without  declaration 
characters  are  single-precision  variables. 

If  type  declaration  statements  are  used,  they  should 
be  at  the  beginning  of  the  program.  The  DEFtype 
statement  must  be  executed  before  you  use  any 
variables  which  it  declares. 
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DEFtype 
Statements 

Example:  Ok 

10  DEFDBL  L-P 

20   DEFSTR  A 

30  DEFINT  X,D-H 

h®  ORDER  =   1-/3:   PRINT  ORDER 

50  ANIMAL  -  "CAT":   PRINT  ANIMAL 

60  X=l 0/3 :   PRINT  X 

RUN 

•3333333333333333 
CAT 

3 
Ok 

Line  10  declares  that  all  variables  beginning  with  the 
letter  L,  M,  N,  O,  or  P  will  be  double-precision 
variables. 

Line  20  causes  all  variables  beginning  with  the  letter 
A  to  be  string  variables. 

Line  30  declares  that  all  variables  beginning  with  the 
letter  X,  D,  E,  F,  G,  or  H  will  be  integer  variables. 
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DEF  USR 
Statement 


Purpose:     Specifies  the  starting  address  of  a  machine  language 
subroutine,  which  is  later  called  by  the  USR 
function. 


Versions:  Cassette 
*** 


Disk 


Advanced 


Compiler 


Format:      DEF  USR[n]=offset 


Remarks:  n 


may  be  any  digit  from  0  to  9-  It  identifies 
the  number  of  the  USR  routine  whose 
address  is  being  specified.  If  n  is  omitted, 
DEF  USRO  is  assumed. 


offset        is  an  integer  expression  in  the  range  0  to 
65  5  35.  The  value  of  offset  is  added  to  the 
current  segment  value  to  obtain  the  actual 
starting  address  of  the  USR  routine.  See 
"DEF  SEG  Statement"  in  this  chapter. 

It  is  possible  to  redefine  the  address  for  a  USR 
routine.  Any  number  of  DEF  USR  statements  may 
appear  in  a  program,  thus  allowing  access  to  as  many 
subroutines  as  necessary.  The  most  recently 
executed  value  is  used  for  the  offset. 

Refer  to  "Appendix  C.  Machine  Language 
Subroutines"  for  complete  information. 


Example: 


200 
210 
500 


DEF  SEG  =  0 
DEF  USR0  =  2'4 
X=USR0 ( Y+2) 


This  example  calls  a  routine  at  absolute  location 
24000  in  memory. 
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DELETE 
Command 


Purpose:     Deletes  program  lines. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  *** 


Format:      DELETE  [Unci]  [  -line!) 

Remarks:   Uriel        is  the  line  number  of  the  first  line  to  be 
deleted. 

Iine2        is  the  line  number  of  the  last  line  to  be 
deleted. 

The  DELETE  command  erases  the  specified  range  of 
lines  from  the  program.  BASIC  always  returns  to 
command  level  after  a  DELETE  is  executed. 

A  period  ( .  )may  be  used  in  place  of  the  line  number 
to  indicate  the  current  line.  If  you  specify  a  line 
number  which  does  not  exist  in  the  program,  an 
"Illegal  function  call"  error  occurs. 

Example:    This  example  deletes  line  40: 


The  next  example  deletes  line  40  through  100, 

inclusive: 


The  last  example  deletes  all  lines  up  to  and  including 
line  40: 


4-76 


DIM 
Statement 


Purpose:     Specifies  the  maximum  values  for  array  variable 
subscripts  and  allocates  storage  accordingly. 


Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  ^**^ 


Format:      DIM  variable{subscripts)  \,variable{subscripts)\. 


Remarks:   variable    is  the  name  to  be  used  for  the  array. 

subscripts  is  a  list  of  numeric  expressions,  separated 
by  commas,  which  define  the  dimensions 
of  the  array. 

When  executed,  the  DIM  statement  sets  all  the 
elements  of  the  specified  numeric  arrays  to  an  initial 
value  of  zero.  String  array  elements  are  all  variable 
length,  with  an  initial  null  value  (zero  length). 

If  an  array  variable  name  is  used  without  a  DIM 
statement,  the  maximum  value  of  its  subscript  is 
assumed  to  be  10.  If  a  subscript  is  used  that  is  greater 
than  the  maximum  specified,  a  "Subscript  out  of 
range"  error  occurs. 

The  minimum  value  for  a  subscript  is  always  0, 
unless  otherwise  specified  with  the  OPTION  BASE 
statement  (see  "OPTION  BASE  Statement"  in  this 
chapter).  The  maximum  number  of  dimensions  for 
an  array  is  255-  The  maximum  number  of  elements 
per  dimension  is  32767.  Both  of  these  numbers  are 
also  limited  by  the  size  of  memory  and  by  the  length 
of  statements. 
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DIM 

Statement 


If  you  try  to  dimension  an  array  more  than  once,  a 
"Duplicate  Definition"  error  occurs.  You  may, 
however,  use  the  ERASE  statement  to  erase  an  array 
so  you  can  dimension  it  again.  For  more  information 
about  arrays,  see  "Arrays"  in  Chapter  3. 

Example:  Ok 

10  WRRMAX-2 

2  0   DIM  S  I  S  f  1  2)  ,   WRR$ (WRRMAX, 2) 

30  DATA  26.5,  37,  8,29,80,  9-9,  f.H800 

'+0  DATA  7,   18,  55,  12,  5,  ^3 

50  FOR    1=0  TO  12 
60  READ  S  i  S (  I  ) 
70  NEXT  I 

80   DATA  SHERRY,    ROBERT,  "A:" 

90  DATA  "HI,   SCOTT1',   HELLO,  GOOD-BYE 

100   DATA  BOCA  RATON,   DELRAY,  MIAMI 

1  10  FOR   [=0  TO  2 :   FOR  J=0  TO  2 

120  READ  WRR$( I , J) 

1 30  NEXT  J ,  I 

}Ud  PRINT  S  i  S ( 3 )  ;  WRRS(2,0) 
RUN 

29  BOCA  RATON 
Ok 

This  example  creates  two  arrays:  a  one-dimensional 
numeric  array  named  SIS  with  13  elements,  SIS(O) 
through  SIS(l  2);  and  a  two-dimensional  string  array 
named  WRRf,  with  three  rows  and  three  columns. 
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DRAW 
Statement 


Purpose:     Draws  an  object  as  specified  by  string. 


Versions:    Cassette      Disk  Advanced 

*** 


Compiler 


Graphics  mode  only. 


Format:      DRAW  string 


Remarks:    You  use  the  DRAW  statement  to  draw  using  a 

graphics  definition  language.  The  language  commands 
are  contained  in  the  string  expression  string.  The 
string  defines  an  object,  which  is  drawn  when  BASIC 
executes  the  DRAW  statement.  During  execution, 
BASIC  examines  the  value  of  string  and  interprets 
single  letter  commands  from  the  contents  of  the 
string.  These  commands  are  detailed  below: 

The  following  movement  commands  begin 
movement  from  the  last  point  referenced.  After  each 
command,  the  last  point  referenced  is  the  last  point 
the  command  draws. 


u 

n 

Move 

up. 

D 

n 

Move 

down. 

L 

n 

Move 

left. 

R 

n 

Move 

right. 

E 

n 

Move 

diagonally  up 

and  right. 

F 

n 

Move 

diagonally  down  and  right. 

G 

n 

Move 

diagonally  down  and  left. 

H 

n 

Move 

diagonally  up 

and  left. 
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DRAW 
Statement 


n  in  each  of  the  preceding  commands  indicates  the 
distance  to  move.  The  number  of  points  moved  is  n 
times  the  scaling  factor  (set  by  the  S  command). 

M  x,y      Move  absolute  or  relative.  If  x  has  a  plus 
sign  (+)  or  a  minus  sign  (-)  in  front  of  it,  it  is 
relative.  Otherwise,  it  is  absolute. 

The  aspect  ratio  of  your  screen  determines  the 
spacing  of  the  horizontal,  vertical,  and  diagonal 
points.  For  example,  the  standard  aspect  ratio  of4/3 
indicates  that  the  horizontal  axis  of  the  screen  is  4/3 
as  long  as  the  vertical  axis.  You  can  use  this 
information  to  determine  how  many  vertical  points 
are  equal  in  length  to  how  many  horizontal  points. 

For  example,  in  medium  resolution  there  are  320 
horizontal  points  and  200  vertical  points.  That 
means  8  horizontal  points  are  equal  in  length  to  5 
vertical  points  if  the  screen  aspect  ratio  is  1/1 .  If  the 
aspect  ratio  is  different,  you  multiply  the  number  of 
vertical  points  by  the  aspect  ratio.  For  example, 
using  the  standard  aspect  ratio  of  4/3,  in  medium 
resolution  8  horizontal  points  are  equal  in  length  to 
20/3  vertical  points,  or  24  horizontal  equal  20 
vertical.  That  is: 

DRAW  "U80  R96  D80  L96" 

produces  a  square  in  medium  resolution.  Following 
similar  reasoning,  again  with  the  standard  screen 
aspect  ratio  of  4/3,  in  high  resolution  48  horizontal 
points  are  equal  in  length  to  20  vertical  points. 
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DRAW 
Statement 


The  following  two  prefix  commands  may  precede 
any  of  the  above  movement  commands. 

B  Move,  but  don't  plot  any  points. 

N  Move,  but  return  to  the  original  position 

when  finished. 

The  following  commands  are  also  available: 

A  n  Set  angles,  n  may  range  fromO  to  3,  where 

0  isO  degrees,  1  is 90,  2  is  180,  and3  is270. 
Figures  rotated  90  or  270  degrees  are 
scaled  so  that  they  appear  the  same  size  as 
with  0  or  180  degrees  on  a  display  screen 
with  standard  aspect  ratio  4/3. 

C  n  Set  color  n.  n  may  range  from  0  to  3  in 

medium  resolution,  and  0  to  1  in  high 
resolution.  In  medium  resolution,  n 
selects  the  color  from  the  current  palette 
as  defined  by  the  COLOR  statement.  0  is 
the  background  color.  The  default  is  the 
foreground  color,  color  number  3-  In 
high  resolution,  n  equal  to  0  (zero) 
indicates  black,  and  the  default  of  1  (one) 
indicates  white. 

S  n  Set  scale  factor,  n  may  range  from  1  to 

255.  n  divided  by  4  is  the  scale  factor.  For 
example,  if  n=\,  then  the  scale  factor  is 
1/4.  The  scale  factor  multiplied  by  the 
distances  given  with  the  U,  D,  L,  R,  E,  F, 
G,  H,  and  relative  M  commands  gives  the 
actual  distance  moved.  The  default  value 
is  4,  so  the  scale  factor  is  1 . 

X  variable;  Execute  substring.  This  allows  you  to 
execute  a  second  string  from  within  a 
string. 
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DRAW 
Statement 


In  all  of  these  commands,  the  n,  x,  ory  argument  can 
be  a  constant  like  123  or  it  can  be  ^variable;  where 
variable  is  the  name  of  a  numeric  variable.  The 
semicolon  ( ;  )  is  required  when  you  use  a  variable 
this  way,  or  in  the  X  command.  Otherwise,  a 
semicolon  is  optional  between  commands.  Spaces 
are  ignored  in  string.  For  example,  you  could  use 
variables  in  a  move  command  this  way: 

M+=X1  ;  ,  -  =  X2 ; 

You  can  also  specify  variables  in  the  form 
WAKPTR$(variab/e),  instead  of  ^variable;.  This  is 
useful  in  programs  that  will  later  be  compiled.  For 
example: 

One  Method  Alternative  Method 

DRAW  "XA$;"  DRAW  '  'X"+VARPTR$ ( A$ ) 

DRAW  "S  =  SCALE;"       DRAW  "S  =  '  '+VARPTR$  (SCALE  ) 

The  X  command  can  be  a  very  useful  part  of  DRAW, 
because  you  can  define  a  part  of  an  object  separate 
from  the  entire  object.  For  example,  a  leg  could  be 
part  of  a  man.  You  can  also  use  X  to  draw  a  string  of 
commands  more  than  255  characters  long. 

When  coordinates  which  are  out  of  range  are  given 
to  DRAW,  the  coordinate  which  is  out  of  range  is 
given  the  closest  valid  value.  In  other  words,  the 
negative  values  become  zero  and  Y  values  greater 
than  199  become  199.  X  values  greater  than  639 
become  639.  X  values  greater  than  319  in  medium 
resolution  wrap  to  the  next  horizontal  line. 
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DRAW 
Statement 


Example:   To  draw  a  box: 


5  SCREEN  1 
10  A=20 

20  DRAW  "U=A;R=A;D=A;L=A; 


To  draw  a  triangle: 


10  SCREEN  1 

20  DRAW  "E15  F15  L 30 


To  create  a  "shooting  star:" 


10  SCREEN   1  ,0  :    COLOR  0,0;  CLS 

20   DRAW  "BM300,25"    '    initial  point 

30  STARS="M+7 , 1 7  M-17,-12  M+20,0  M-17,12  M+7,-17 

^0  FOR  SCALE=1   TO  40  STEP  2 

50  DRAW  "C1;S  =  SCALE;    BM- 2 ,0 ; XSTAR$ ; 1 1 

60  NEXT 


C/3 

H 
> 

m 

m 
Z 
H 
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EDIT 
Command 


Purpose:     Displays  a  line  for  editing. 

Versions:    Cassette      Disk      Advanced  Compiler 


Format:      EDIT  line 


Remarks:   line  is  the  line  number  of  a  line  existing  in  the 

program.  If  there  is  no  such  line,  an 
"Undefined  line  number"  error  occurs.  A 
period  ( .  )  can  be  used  for  the  line  number 
to  refer  to  the  current  line. 

The  EDIT  statement  simply  displays  the  line 
specified  and  positions  the  cursor  under  the  first 
digit  of  the  line  number.  The  line  may  then  be 
modified  as  described  under  "The  BASIC  Program 
Editor"  in  Chapter  2. 

A  period  ( .  )  can  be  used  for  the  line  number  to  refer 
to  the  current  line.  For  example,  if  you  have  just 
entered  a  line  and  wish  to  go  back  and  change  it,  the 
command  EDIT  .  will  redisplay  the  line  for  editing. 

LIST  may  also  be  used  to  display  program  lines  for 
changing.  Refer  to  "LIST  Command"  in  this 
chapter. 
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END 
Statement 


Purpose:     Terminates  program  execution,  closes  all  files,  and 
returns  to  command  level. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:  END 


Remarks:    END  statements  may  be  placed  anywhere  in  the 

program  to  terminate  execution.  END  is  different 
from  STOP  in  two  ways: 

•  END  does  not  cause  a  "Break"  message  to  be 
printed. 

•  END  closes  all  files. 

An  END  statement  at  the  end  of  a  program  is 
optional.  BASIC  always  returns  to  command  level 
after  an  END  is  executed. 


Example:    520   IF  K  1 000  THEN  END  ELSE  GOTO  20 

This  example  ends  the  program  if  K  is  greater  than 
1000;  otherwise,  the  program  branches  to  line 
number  20. 
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EOF 

Function 


Purpose:     Indicates  an  end  of  file  condition. 

Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:     v  =  EOVifilenum) 

Remarks:  filenum     is  the  number  specified  on  the  OPEN 
statement. 

The  EOF  function  is  useful  for  avoiding  an  "Input 
past  end"  error.  EOF  returns  -1  (true)  if  end  of  file 
has  been  reached  on  the  specified  file.  A  0  (zero)  is 
returned  if  end  of  file  has  not  been  reached. 

EOF  is  meaningful  only  for  a  file  opened  for 
sequential  input  from  diskette  or  cassette,  or  for  a 
communications  file.  A  -1  for  a  communications  file 
means  that  the  buffer  is  empty. 

Example:    10  OPEN  "DATA"  FOR  INPUT  AS  -1 
20  C=0 

30    I F  EOF  I  1  J    THEN  END 
40    I  NPUT   ••  1  ,M  (C) 
50  C  =  C  +  1  :   GOTO  30 

This  example  reads  information  from  the  sequential 
file  named  "  DATA".  Values  are  read  into  the  array  M 
until  end  of  file  is  reached. 


4-86 


ERASE 
Statement 


Purpose:     Eliminates  arrays  from  a  program. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      ERASE  arrayname\,arrayname].. 


Remarks:   arrayname  is  the  name  of  an  array  you  want  to 

erase. 

You  might  want  to  use  the  ERASE  statement  if  you 
are  running  short  of  storage  space  while  running 
your  program.  After  arrays  are  erased,  the  space  in 
memory  which  had  been  allocated  for  the  arrays  may 
be  used  for  other  purposes. 

ERASE  can  also  be  used  when  you  want  to 
redimension  arrays  in  your  program.  If  you  try  to 
redimension  an  array  without  first  erasing  it,  a 
"Duplicate  Definition"  error  occurs. 

The  CLEAR  command  is  used  to  erase  all  variables 
from  the  work  area. 


4-87 


Statement 

Ok 


10  START=FRE  ("")  ^\ 

20  DIM  BIG (100 ,100) 

30  M  I  DDLE=FRE  (Hl ') 

^0  ERASE  BIG 

50  DIM  BIG (10, 10) 

60  F I NAL=FRE ("") 

70  PRINT  START .  MIDDLE,  FINAL 

RUN 

62808  21980  62289 

Ok 

This  example  uses  the  FRE  function  to  illustrate 
how  ERASE  can  be  used  to  free  memory.  The  array 
BIG  used  up  about  40K-bytes  of  memory 
(62808-21980)  when  it  was  dimensioned  as 
BIG(100,100).  After  it  was  erased,  it  could  be 
redimensioned  to  BIG(10,10),  and  it  only  took  up  a 
little  more  than  500  bytes  (62808-62289). 

The  actual  values  returned  by  the  FRE  function  may 
be  different  on  your  computer. 
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ERR  and  ERL 
Variables 


Purpose:     Return  the  error  code  and  line  number  associated 
with  an  error. 


Versions:    Cassette      Disk      Advanced  Compiler 

Format:     v  =  ERR 

v  =  ERL 


Remarks:  The  variable  ERR  contains  the  error  code  for  the  last 
error,  and  the  variable  ERL  contains  the  line  number 
of  the  line  in  which  the  error  was  detected.  The  ERR 
and  ERL  variables  are  usually  used  in  IF.. .THEN 
statements  to  direct  program  flow  in  the  error 
handling  routine  (refer  to  "ON  ERROR  Statement" 
in  this  chapter). 

If  you  do  test  ERL  in  an  IF. ..THEN  statement,  be 
sure  to  put  the  line  number  on  the  right  side  of  the 
relational  operator,  like  this: 

IF  ERL  =  line  number  THEN  ... 

The  number  must  be  on  the  right  side  of  the 
operator  for  it  to  be  renumbered  by  RENUM. 


If  the  statement  that  caused  the  error  was  a  direct 
mode  statement,  ERL  will  contain  655  35.  Since  you 
do  not  want  this  number  to  be  changed  during  a 
RENUM,  if  you  want  to  test  whether  an  error 
occurred  in  a  direct  mode  statement  you  should  use 
the  form: 


IF  65535  =  ERL  THEN  ... 
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ERR  and  ERL  can  be  set  using  the  ERROR 
statement  (see  next  section). 

BASIC  error  codes  are  listed  in  "Appendix  A. 
Messages." 

Example:    10  ON  ERROR  GOTO  100 

20  LPRINT  "This  goes  to  the  printer" 
30  END 

100   IF  ERR-27  THEN  LOCATE  23, h 
PRINT  "Check  printer":  RESUME 

This  example  tests  for  a  common  problem: 
forgetting  to  put  paper  in  the  printer,  or  forgetting 
to  switch  it  on. 


ERROR 
Statement 


Purpose:     •     Simulates  the  occurrence  of  a  BASIC  error;  or 
•     Allows  you  to  define  your  own  error  codes. 

Versions:    Cassette      Disk      Advanced  Compiler 

##*  #** 

Format:      ERROR  n 


Remarks:   n      must  be  an  integer  expression  between  0  and 
255- 

If  the  value  of  n  is  the  same  as  an  error  code  used  by 
BASIC  (see  "Appendix  A.  Messages"),  the  ERROR 
statement  simulates  the  occurrence  of  that  error.  If 
an  error  handling  routine  has  been  defined  by  the 
ON  ERROR  statement,  the  error  routine  is  entered. 
Otherwise  the  error  message  corresponding  to  the 
code  is  displayed,  and  execution  halts.  (See  first 
example  below.) 

To  define  your  own  error  code,  use  a  value  that  is 
different  from  any  used  by  BASIC.  (We  suggest  you 
use  the  highest  available  values;  for  example,  values 
greater  than  200.)  This  new  error  code  may  then  be 
tested  in  an  error  handling  routine,  just  like  any 
other  error.  (See  second  example  below.) 

If  you  define  your  own  code  in  this  way,  and  you 
don't  handle  it  in  an  error  handling  routine,  BASIC 
displays  the  message  "Unprintable  error,"  and 
execution  halts. 
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ERROR 
Statement 


Example:    The  first  example  simulates  a  "String  too  long" 
error. 


The  next  example  is  a  part  of  a  game  program  that 
allows  you  to  make  bets.  By  using  an  error  code  of 
210,  which  BASIC  doesn't  use,  the  program  traps  the 
error  if  you  exceed  the  house  limit. 

110  ON   ERROR  GOTO  h00 

120    I'jPiJT   !,WHAT    IS   YOUR  B  E  T  "  ;  B 

1  30    I  r  B       5000  THEN   ERROR,  2  1  0 


Ok 

10  T  =  15 
20  ERROR  T 
RUN 


S  E  i'  i  r.q  Loo 
Ok 


onq    i  ii    line  20 


400  IF  ERR 
4 1 0    IF   E  R  L 


2 1 0  THEN  PR  i  NT  "HOUSE 
130  THEN   RESUME  120 
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EXP 
Function 


Purpose:    Calculates  the  exponential  function. 


Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:     v  =  EXP(*) 


Remarks:  x        may  be  any  numeric  expression. 

This  function  returns  the  mathematical  number  e 
raised  to  the  x  power,  e  is  the  base  for  natural 
logarithms.  An  overflow  occurs  if  x  is  greater  than 
88.02969. 


Example: 


This  example  calculates  e  raised  to  the  (2-1)  power, 
which  is  simply  e. 
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FIELD 
Statement 


Purpose:  Allocates  space  for  variables  in  a  random  file  buffer. 
Versions:    Cassette     Disk      Advanced  Compiler 


Format:      FIELD  \jf\filenum,  width  AS  stringvar  [,width 
AS  stringvar] . . . 


Remarks:   filenum    is  the  number  under  which  the  file  was 
opened. 

width       is  a  numeric  expression  specifying  the 
number  of  character  positions  to  be 
allocated  to  stringvar. 

stringvar  is  a  string  variable  which  will  be  used  for 
random  file  access. 

A  FIELD  statement  defines  variables  that  are  used  to 
get  data  out  of  a  random  buffer  after  a  GET  or  to 
enter  data  into  the  buffer  for  a  PUT. 

The  statement: 

F I  ELD   1,    20  AS  N$,    10  AS    IDS,   k&  AS  ADDS 

allocates  the  first  20  positions  (bytes)  in  the  random 
file  buffer  to  the  string  variable  N$,  the  next  10 
positions  to  ID$,  and  the  next  40  positions  to 
ADD$.  FIELD  does  not  actually  place  any  data  into 
the  random  file  buffer.  This  is  done  by  the  LSET  and 
RSET  statements  (see  "LSET  and  RSET 
Statements"  in  this  chapter). 
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FIELD 
Statement 


FIELD  does  not  "remove"  data  from  the  file  either. 
Information  is  read  from  the  file  into  the  random  file 
buffer  with  the  GET  (file)  statement.  Information  is 
read  from  the  buffer  by  simply  referring  to  the 
variables  defined  in  the  FIELD  statement. 


The  total  number  of  bytes  allocated  in  a  FIELD 
statement  must  not  exceed  the  record  length  that 
was  specified  when  the  file  was  opened.  Otherwise,  a 
"Field  overflow"  error  occurs. 


Any  number  of  FIELD  statements  may  be  executed 
for  the  same  file  number,  and  all  FIELD  statements 
that  have  been  executed  are  in  effect  at  the  same 
time.  Each  new  FIELD  statement  redefines  the 
buffer  from  the  first  character  position,  so  this  has 
the  effect  of  having  multiple  field  definitions  for  the 
same  data. 


Note:  Be  careful  about  using  a  fielded  variable  name 
in  an  input  or  assignment  statement.  Once  a  variable 
name  is  defined  in  a  FIELD  statement,  it  points 
to  the  correct  place  in  the  random  file  buffer.  If 
a  subsequent  input  statement  or  LET  statement 
with  that  variable  name  on  the  left  side  of  the 
equal  sign  is  executed,  the  variable  is  moved  to 
string  space  and  is  no  longer  in  the  file  buffer. 

See  "Appendix  B.  BASIC  Diskette  Input  and 
Output"  for  a  complete  explanation  of  how  to  use 
random  files. 
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FIELD 
Statement 


Example:    10  OPEN  "A:CUST"  AS  #1 

20  FIELD  1,  2  AS  CUSTN0$,   30  AS  CUSTNAME$ , 

35  AS  ADDR$ 

30  LSET  CUSTNAME$+"0 1 NE I L  INC" 

<40  LSET  ADDR$+"5Cf  SE  12TH  ST,  NY,  NY" 

50  LSET  CUSTNO$=MKI$(7850) 

60  PUT  1,1 

70  GET  1,1 

80  CNUM. ■=  CVI  (CUSTN0$)  :  N$  =  CUSTNAME$ 

90  PRINT  CNUM',  N$,  ADDR$ 

This  example  opens  a  file  named  "CUST"  as  a 
random  file.  The  variable  CUSTNO$  is  assigned  to 
the  first  2  positions  in  each  record,  CUSTNAME$  is 
assigned  to  the  next  30  positions,  and  ADDR$  is 
assigned  to  the  next  35  positions.  Lines  30  through 
50  put  information  into  the  buffer,  and  the  PUT 
statement  in  line  60  writes  the  buffer  to  the  file.  Line 
70  reads  back  that  same  record,  and  line  90  displays 
the  three  fields.  Note  in  line  80  that  it  is  okay  to  use  a 
variable  name  which  was  defined  in  a  FIELD 
statement  on  the  right  side  of  an  assignment 
statement. 
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FILES 
Command 


Purpose:     Displays  the  names  of  files  residing  on  a  diskette. 

The  FILES  command  in  BASIC  is  similar  to  the 
DIR.  command  in  DOS. 


Versions:    Cassette     Disk      Advanced  Compiler 


Format:      FILES  [filespec  ] 


Remarks:  filespec 


is  a  string  expression  for  the  file 
specification  as  explained  under  "Naming 
Files"  in  Chapter  3.  If  filespec  is  omitted, 
all  the  files  on  the  DOS  default  drive  will 
be  listed. 


All  files  matching  the  filename  are  displayed.  The 
filename  may  contain  question  marks  (?).  A  question 
mark  matches  any  character  in  the  name  or 
extension.  An  asterisk  (*)  as  the  first  character  of  the 
name  or  extension  will  match  any  name  or  any 
extension. 


If  a  drive  is  specified  as  part  of  filespec,  then  files 
which  match  the  specified  filename  on  the  diskette 
in  that  drive  are  listed.  Otherwise,  the  DOS  default 
drive  is  used. 
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FILES 
Command 

Example: 

This  displays  all  files  on  the  DOS  default  diskette 
drive. 


This  displays  all  files  with  an  extension  of  .BAS  on 
the  DOS  default  diskette  drive. 


This  displays  all  files  on  drive  B:. 


This  lists  all  files  on  the  DOS  default  drive  which 
have  a  filename  beginning  with  TEST  followed  by 
two  or  less  other  characters,  and  an  extension  of 
.BAS. 
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FIX 
Function 


Purpose:     Truncates  x  to  an  integer. 

Versions:    Cassette      Disk      Advanced  Compiler 

#*#  *##  ### 


Format:     v  =  FIX(x) 

Remarks:  x  may  be  any  numeric  expression. 

FIX  strips  all  digits  to  the  right  of  the  decimal  point 
and  returns  the  value  of  the  digits  to  the  left  of  the 
decimal  point. 

The  difference  between  FIX  and  INT  is  that  FIX 
does  not  return  the  next  lower  number  whenx  is 
negative. 

See  the  INT  and  CINT  functions,  which  also  return 
integers. 

Example:  Ok 

i  R.  !  "  j  1    F  !  x'  i  '+5  .  6  / 

J,  c 
j 

Ok 

PRINT   F  I  X  i'-2.8  9  ' 

- 1 

Ok 

Note  in  the  examples  how  FIX  does  not  round  the 
decimal  part  when  it  converts  to  an  integer. 
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FOR  and  NEXT 
Statements 


Purpose:     Performs  a  series  of  instructions  in  a  loop  a  given 
number  of  times. 


Versions:    Cassette     Disk      Advanced  Compiler 


Format:      FOR  variable=x  TO  y  [STEP  z] 


NEXT  [variable]  ^variable] . . . 


Remarks:  variable 


is  an  integer  or  single-precision  variable  to 
be  used  as  a  counter. 


y 


is  a  numeric  expression  which  is  the  initial 
value  of  the  counter. 

is  a  numeric  expression  which  is  the  final 
value  of  the  counter. 


z  is  a  numeric  expression  to  be  used  as  an 

increment. 

The  program  lines  following  the  FOR  statement  are 
executed  until  the  NEXT  statement  is  encountered. 
Then  the  counter  is  incremented  by  the  amount 
specified  by  the  STEP  value  (z).  If  you  do  not  specify 
a  value  forz,  the  increment  is  assumed  to  be  1  (one). 
A  check  is  performed  to  see  if  the  value  of  the 
counter  is  now  greater  than  the  final  value  y.  If  it  is 
not  greater,  BASIC  branches  back  to  the  statement 
after  the  FOR  statement  and  the  process  is  repeated. 
If  it  is  greater,  execution  continues  with  the 
statement  following  the  NEXT  statement.  This  is  a 
FOR.. .NEXT  loop. 
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Statements 


If  the  value  of  z  is  negative,  the  test  is  reversed.  The 
counter  is  decremented  each  time  through  the  loop, 
and  the  loop  is  executed  until  the  counter  is  less  than 
the  final  value. 

The  body  of  the  loop  is  skipped  ifx  is  already  greater 
thany  when  the  STEP  value  is  positive,  or  if  x  is  less 
than  7  when  the  STEP  value  is  negative.  If  z  is  zero, 
an  infinite  loop  will  be  created  unless  you  provide 
some  way  to  set  the  counter  greater  than  the  final 
value. 

Program  performance  will  be  improved  if  you  use 
integer  counters  whenever  possible. 


Nested  Loops 

FOR.. .NEXT  loops  may  be  nested;  that  is,  one 
FOR... NEXT  loop  may  be  placed  inside  another 
FOR.. .NEXT  loop.  When  loops  are  nested,  each 
loop  must  have  a  unique  variable  name  as  its 
counter.  The  NEXT  statement  for  the  inside  loop 
must  appear  before  that  for  the  outside  loop.  If 
nested  loops  have  the  same  end  point,  a  single  NEXT 
statement  may  be  used  for  all  of  them. 

A  NEXT  statement  of  the  form: 

NEXT  varl,  var2,  var3  ... 

is  equivalent  to  the  sequence  of  statements: 

NEXT  varl 
NEXT  var2 
NEXT  var3 
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FOR  and  NEXT 
Statements 

The  variable(s)  in  the  NEXT  statement  may  be 
omitted,  in  which  case  the  NEXT  statement  matches 
the  most  recent  FOR  statement.  If  you  are  using 
nested  FOR.. .NEXT  loops,  you  should  include  the 
variable(s)  on  all  the  NEXT  statements.  It  is  a  good 
idea  to  include  the  variables  in  order  to  avoid 
confusion;  but  it  can  be  necessary  if  you  do  any 
branching  out  of  nested  loops.  (However,  using 
variable  names  on  the  NEXT  statements  will  cause 
your  program  to  execute  somewhat  slower.) 

If  a  NEXT  statement  is  encountered  before  its 
corresponding  FOR  statement,  a  "NEXT  without 
FOR"  error  occurs. 


Example:   The  first  example  shows  a  FOR... NEXT  loop  with  a 
STEP  value  of  2. 

Ok 

10  J- 10:  K=30 

20  FOR   1=1   TO  J   STEP  2 

30  PR ! NT    I ; 

^0  K--K+10 

50  PRINT  K 

60  NEXT 


RUN 

1 

3 

60 

I 

Q 

80 

Ok 
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FOR  and  NEXT 
Statements 


In  the  next  example,  the  loop  does  not  execute 
because  the  initial  value  of  the  loop  is  more  than  the 
final  value: 


Ok 

10  J=0 

20  FOR   1+1   TO  J 

30  PRINT  I 

40  NEXT  I 

RUN 

Ok 


In  the  last  example,  the  loop  executes  ten  times.  The 
final  value  for  the  loop  variable  is  always  set  before 
the  initial  value  is  set.  (This  is  different  from  some 
other  versions  of  BASIC,  which  set  the  initial  value 
of  the  counter  before  setting  the  final  value.  In 
another  BASIC  the  loop  in  this  example  might 
execute  six  times.) 


Ok 

10  1-5 

20  FOR   1-1   TO   I +5 
30  PR  i  NT   I  ; 
4  0  NEXT 
RUN 

12  3^56 
Ok 


3  9 
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FRE 

Function 


Purpose:    Returns  the  number  of  bytes  in  memory  that  are  not 
being  used  by  BASIC.  This  number  does  not  include 
the  size  of  the  reserved  portion  of  the  interpreter 
workarea  (normally  2.5K  to  4K-bytes). 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  ^**^ 

Format:     v  =  FRE(.r) 
v  =  FRE(*#) 

Remarks:  x  and  x$  are  dummy  arguments. 

Since  strings  in  BASIC  can  have  variable  lengths 
(each  time  you  do  an  assignment  to  a  string  its  length 
may  change),  strings  are  manipulated  dynamically. 
For  this  reason,  string  space  may  become 
fragmented. 

FRE  with  any  string  value  causes  a  housecleaning 
before  returning  the  number  of  free  bytes. 
Housecleaning  is  when  BASIC  collects  all  of  its  useful 
data  and  frees  up  unused  areas  of  memory  that  were 
once  used  for  strings.  The  data  is  compressed  so  you 
can  continue  until  you  really  run  out  of  space. 

BASIC  automatically  does  a  housecleaning  when  it  is 
running  out  of  usable  workarea.  You  might  want  to 
use  FRE("")  periodically  to  get  shorter  delays  for 
each  housecleaning.  Be  patient:  housecleaning  may 
take  a  while. 
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FRE 
Function 


CLEAR  ,«  sets  the  maximum  number  of  bytes  for 
the  BASIC  workspace.  FRE  returns  the  amount  of 
free  storage  in  the  BASIC  workspace.  If  nothing  is  in 
the  workspace,  then  the  value  returned  by  FRE  will 
be  2.5K  to  4K-bytes  (the  size  of  the  reserved 
interpreter  workarea)  smaller  than  the  number  of 

Example:  Ok 

PRINT  F  R  E  f  0 ) 
Ok 

The  actual  value  returned  by  FRE  on  your  computer 
may  differ  from  this  example. 


> 

m 

S 

tn 
Z 
H 
00 
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GET 

Statement  (Files) 


Purpose:     Reads  a  record  from  a  random  file  into  a  random 
buffer. 


Versions:    Cassette     Disk      Advanced  Compiler 

***  ***  *** 


Format:      GET  \jf\filenum  [,  number] 

Remarks:  filenum     is  the  number  under  which  the  file  was 
opened. 

number  is  the  number  of  the  record  to  be  read,  in 
the  range  1  to  32767.  If  number  is  omitted, 
the  next  record  (after  the  last  GET)  is  read 
into  the  buffer. 

After  a  GET  statement,  INPUT  #,  LINE  INPUT  #, 
or  references  to  variables  defined  in  the  FIELD 
statement  may  be  used  to  read  characters  from  the 
random  file  buffer.  Refer  to  "Appendix  B.  BASIC 
Diskette  Input  and  Output"  for  more  complete 
information  on  using  GET. 

Because  BASIC  and  DOS  block  as  many  records  as 
possible  in  5 1 2  byte  sectors,  the  GET  statement  does 
not  necessarily  perform  a  physical  read  from  the 
diskette. 

GET  may  also  be  used  for  communications  files.  In 
this  case  number  is  the  number  of  bytes  to  read  from 
the  communications  buffer.  This  number  cannot 
exceed  the  value  set  by  the  LEN  option  on  the 
OPEN  "COM...  statement. 


4-106 


Statement 


GET 
(Files) 


Example:    \<D  GPLN  :f,UST 
2  0   F  i  t  i  D    I  ,  .50 


c 


/  \  J 


CUS^NAf^ 


30 


ADDRS , 


7  L 


30  GL  T  ! 

■i0  PR  !  NT   LljS  FNAMFS  ,    ADDR$  ,    CI  FYS 

This  example  opens  the  file  "CUST"  for  random 
access,  with  fields  defined  in  line  20.  The  GET 
statement  on  line  30  reads  a  record  into  the  file 
buffer.  Line  40  displays  the  information  from  the 
record  that  was  read. 
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GET 

Statement  (Graphics) 


Purpose:     Reads  points  from  an  area  of  the  screen. 

Versions:    Cassette      Disk      Advanced  Compiler 

*#*  **  * 

Graphics  mode  only. 

Format:      GET  (xl  ,yl)-{x2,y2),arrayname 

Remarks:   {xl,yl),  (x2,y2) 

are  coordinates  in  either  absolute  or 
relat^  e  form.  Refer  to  "Specifying 
Coordinates"  under  "Graphics  Modes"  in 
Chapter  3  for  information  on  coordinates, 

arrayname  is  the  name  of  the  array  you  want  to  hold 
the  information. 


GET  reads  the  colors  of  the  points  within  the 
specified  rectangle  into  the  array.  The  specified 
rectangle  has  points  {xl,yl)  and  (x2,y2)  as  opposite 
corners.  (This  is  the  same  as  the  rectangle  drawn  by 
the  LINE  statement  using  the  B  option.) 

GET  and  PUT  can  be  used  for  high  speed  object 
motion  in  graphics  mode.  You  might  think  of  GET 
and  PUT  as  "bit  pump"  operations  which  move  bits 
onto  (PUT)  and  off  of  (GET)  the  screen.  Remember 
that  PUT  and  GET  are  also  used  for  random  access 
files,  but  the  syntax  of  these  statements  is  different. 
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GET 

Statement  (Graphics) 


The  array  is  used  simply  as  a  place  to  hold  the  image 
and  must  be  numeric;  it  may  be  any  precision, 
however.  The  required  size  of  the  array,  in  bytes,  is: 

A+lNY{(x*bitsperpixel+7)/8)*y 

where  x  and  y  are  the  lengths  of  the  horizontal  and 
vertical  sides  of  the  rectangle,  respectively.  The 
value  of  bitsperpixel  is  2  in  medium  resolution,  and  1 
in  high  resolution. 

For  example,  suppose  we  want  to  use  the  GET 
statement  to  get  a  10  by  12  image  in  medium 
resolution.  The  number  of  bytes  required  is 
4+INT((10*2+7)/8)*12,  or  40  bytes.  The  bytes  per 
element  of  an  array  are: 

•  2  for  integer 

•  4  for  single-precision 

•  8  for  double-precision 

Therefore,  we  could  use  an  integer  array  with  at  least 
20  elements. 

The  information  from  the  screen  is  stored  in  the 
array  as  follows: 

1.  two  bytes  giving  the  x  dimension  in  bits 

2.  two  bytes  giving  the  y  dimension  in  bits 

3.  the  data  itself 


It  is  possible  to  examine  the  x  and  y  dimensions  and 
even  the  data  itself  if  an  integer  array  is  used.  The  x 
dimension  is  in  element  0  of  the  array,  and  the  y 
dimension  is  in  element  1.  Keep  in  mind,  however, 
that  integers  are  stored  lowbyte  first,  thenhighbyte; 
but  the  data  is  actually  transferred  high  byte  first, 
then  low  byte. 
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GET 

Statement  (Graphics) 


The  data  for  each  row  of  points  in  the  rectangle  is  left 
justified  on  a  byte  boundary,  so  if  there  are  less  than  a 
multiple  of  eight  bits  stored,  the  rest  of  the  byte  will 
be  filled  with  zeros. 

PUT  and  GET  work  significantly  faster  in  medium 
resolution  when  xl  MOD  4  is  equal  to  zero,  and  in 
high  resolution  when  xl  MOD  8  is  equal  to  zero.  This 
is  a  special  case  where  the  rectangle  boundaries  fall 
on  the  byte  boundaries. 
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GOSUB  and  RETURN 
Statements 


Purpose:     Branches  to  and  returns  from  a  subroutine. 


Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  *** 


Format:      GOSUB  line 


RETURN 


Remarks:    line  is  the  line  number  of  the  first  line  of  the 
subroutine. 

A  subroutine  may  be  called  any  number  of  times  in  a 
program,  and  a  subroutine  may  be  called  from  within 
another  subroutine.  Such  nesting  of  subroutines  is 
limited  only  by  available  memory. 

The  RETURN  statement  causes  BASIC  to  branch 
back  to  the  statement  following  the  most  recent 
GOSUB  statement.  A  subroutine  may  contain  more 
than  one  RETURN  statement,  if  you  want  to  return 
from  different  points  in  the  subroutine.  Subroutines 
may  appear  anywhere  in  the  program. 

To  prevent  your  program  from  accidentally  entering 
a  subroutine,  you  may  want  to  put  a  STOP,  END,  or 
GOTO  statement  in  front  of  the  subroutine  to  direct 
program  control  around  it. 

Use  ON... GOSUB  to  branch  to  different 
subroutines  based  on  the  result  of  an  expression. 
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GOSUB  and  RETURN 
Statements 


Example:  Ok 

10  GOSUB 

20  PRINT  "BACK  FROM  SUBROUTINE1" 
30  END 

kg!  PRINT  "SUBROUTINE"; 

50  PRINT  "  IN"; 

60  PRINT  "  PROGRESS" 

70  RETURN 

RUN 

SUBROUTINE   IN  PROGRESS 
BACK  FROM  SUBROUTINE 
Ok 

This  example  shows  how  a  subroutine  works.  The 
GOSUB  in  line  10  calls  the  subroutine  in  line  40.  So 
the  program  branches  to  line  40  and  starts  executing 
statements  there  until  it  sees  the  RETURN 
statement  in  line  70.  At  that  point  the  program  goes 
back  to  the  statement  after  the  subroutine  call;  that 
is,  it  returns  to  line  20.  The  END  statement  in  line  30 
prevents  the  subroutine  from  being  performed  a 
second  time. 


GOTO 
Statement 


Purpose:     Branches  unconditionally  out  of  the  normal 
program  sequence  to  a  specified  line  number. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      GOTO  line 


Remarks:   line  is  the  line  number  of  a  line  in  the  program. 

If  line  is  the  line  number  of  an  executable  statement, 
that  statement  and  those  following  are  executed.  If 
line  refers  to  a  non-executable  statement  (such  as 
REM  or  DATA),  the  program  continues  at  the  first 
executable  statement  encountered  after  line. 


The  GOTO  statement  can  be  used  in  direct  mode  to 
re-enter  a  program  at  a  desired  point.  This  can  be 
useful  in  debugging. 

Use  ON. ..GOTO  to  branch  to  different  lines  based 
on  the  result  of  an  expression. 
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GOTO 
Statement 


Example:  Ok 

5    DATA  5,7,12 

10  READ  R 

20  PR  I  NT  "R  =";R1 

30  A  -  3-  1V---IT2 

^0  PRINT  "AREA  =M;A 

50  GOTO  5 

RUN 

R  =  5  AREA  =78.5 

R  =  7  AREA  =  153-86 

R  -  12  AREA  =  ^52  .  16 

Out  of  data   in  10 
Ok 

The  GOTO  statement  in  line  50  puts  the  program 
into  an  infinite  loop,  which  is  stopped  when  the 
program  runs  out  of  data  in  the  DATA  statement. 
(Notice  how  branching  to  the  DATA  statement  did 
not  add  additional  values  to  the  internal  data  table.) 
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HEX$ 
Function 


Purpose:     Returns  a  string  which  represents  the  hexadecimal 
value  of  the  decimal  argument. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      v$  =  HEX$(tz) 


Remarks:   n      is  a  numeric  expression  in  the  range -32768  to 
65535. 

If  n  is  negative,  the  two's  complement  form  is  used. 
That  is,  HEX$(-7?)  is  the  same  as  HEX$(655  36-*). 

See  the  OCT$  function  for  octal  conversion. 


Example:   The  following  example  uses  the  HEX$  function  to 
figure  the  hexadecimal  representation  for  the  two 
decimal  values  which  are  entered. 
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IF 

Statement 


Purpose:     Makes  a  decision  regarding  program  flow  based  on 
the  result  of  an  expression. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 

Format:      IF  expression  [,]THEN  clause  [ELSE  clause] 
IF  expression  [JGOTO  line  [[,]ELSE  clause] 


Remarks:   expression  may  be  any  numeric  expression. 

clause  may  be  a  BASIC  statement  or  a  sequence  of 
statements  (separated  by  colons);  or  it  may 
be  simply  the  number  of  a  line  to  branch  to 

line  is  the  line  number  of  a  line  existing  in  the 

program. 

If  the  expression  is  true  (not  zero),  the  THEN  or 
GOTO  clause  is  executed.  THEN  may  be  followed 
by  either  a  line  number  for  branching  or  one  or  more 
statements  to  be  executed.  GOTO  is  always 
followed  by  a  line  number. 

If  the  result  of  expression  is  false  (zero),  the  THEN  or 
GOTO  clause  is  ignored  and  the  ELSE  clause,  if 
present,  is  executed.  Execution  continues  with  the 
next  executable  statement. 

If  you  enter  an  IF.. .THEN  statement  in  direct  mode, 
and  it  directs  control  to  a  line  number,  then  an 
"Undefined  line  number"  error  results  unless  you 
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previously  entered  a  line  with  the  specified  line 
number. 

Note:    When  using  IF  to  test  equality  for  a 
value  that  is  the  result  of  a  single-  or 
double-precision  computation,  remember  that 
the  internal  representation  of  the  value  may  not 
be  exact.  (This  is  because  single-  and 
double-precision  values  are  stored  internally  in 
floating  point  binary  format.)  Therefore,  the 
test  should  be  against  the  range  over  which  the 
accuracy  of  the  value  may  vary.  For  example,  to 
test  a  computed  variable  A  against  the  value  1 .0, 
use: 


This  test  returns  a  true  result  if  the  value  of  A  is 
1.0  with  a  relative  error  of  less  than  1.0E-6. 

Also  note  that  IF...  THEN. ..ELSE  is  just  one 
statement.  That  is,  the  ELSE  clause  cannot  be  a 
separate  program  line.  For  example: 


is  invalid.  Instead,  it  should  be: 
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Nesting  of  IF  Statements:    IF.. .THEN.. .ELSE 
statements  may  be  nested.  Nesting  is  limited  only  by 
the  length  of  the  line.  For  example, 

IF  X  Y  THEN  PRINT  "GREATER"  ELSE    IF  Y  X 

THEN   PRINT   "LESS  THAN 1 !  ELSE   PRINT  "EQUAl 

is  a  valid  statement.  If  the  statement  does  not 
contain  the  same  number  of  ELSE  and  THEN 
clauses,  each  ELSE  is  matched  with  the  closest 
unmatched  THEN.  For  example, 

IF  A=B  THEN    IF   B-C  THEN  PRINT  "A=C" 
ELSE  PRINT  "A  C" 

will  not  print  "A<>C"  when  A<>B. 

Example:    This  statement  gets  record  I  if  I  is  not  zero: 

200    IF    I    THEN  GET   ■■■■  1  ,  I 

In  the  next  example,  if  I  is  between  10  and  20,  DB  is 
calculated  and  execution  branches  to  line  300.  If  I  is 
not  in  this  range,  the  message  "OUT  OF  RANGE"  is 
printed.  Note  the  use  of  two  statements  in  the 
THEN  clause. 

100    IF    (I    10)    AND    ( I ■  20 )  THEN 
DB-  1982-  1  :   GOTO  300 
ELSE  PRINT  "OUT  OF  RANGE' 

This  next  statement  causes  printed  output  to  go  to 
either  the  screen  or  the  printer,  depending  on  the 
value  of  a  variable  (IOFLAG).  If  IOFLAG  is  false 
(zero),  output  goes  to  the  printer;  otherwise,  output 
goes  to  the  screen: 

2  10    IF   IOFLAG  THEN  PRINT  AS   ELSE   LP  R I  NT  AS 
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INKEY$ 
Variable 


Purpose:     Reads  a  character  from  the  keyboard. 


Versions:    Cassette      Disk      Advanced  Compiler 
*  *  *  *  *  *  **  *  **  * 


Format:     v$  =  INKEY$ 


Remarks:  INKEY$  only  reads  a  single  character,  even  if  there 
are  several  characters  waiting  in  the  keyboardbuffer. 
The  returned  value  is  a  zero-,  one-,  or  two-character 
string. 


•  A  null  string  (length  zero)  indicates  that  no 
character  is  pending  at  the  keyboard. 

•  A  one-character  string  contains  the  actual 
character  read  from  the  keyboard. 

•  A  two-character  string  indicates  a  special 
extended  code.  The  first  character  will  be  hex 
00.  For  a  complete  list  of  these  codes,  see 
"Appendix  G.  ASCII  Character  Codes." 

You  must  assign  the  result  of  INKEY$  to  a  string 
variable  before  using  the  character  with  any  BASIC 
statement  or  function. 


While  INKEY$  is  being  used,  no  characters  are 
displayed  on  the  screen  and  all  characters  are  passed 
through  to  the  program  except  for: 


•  Ctrl-Break,  which  stops  the  program 

•  Ctrl-Num  Lock,  which  sends  the  system  into  a 
pause  state 

•  Alt-Ctrl-Del,  which  does  a  System  Reset 

•  PrtSc,  which  prints  the  screen 


4-119 


INKEY$ 
Variable 


If  you  press  Enter  in  response  to  INKEY$,  the 
carriage  return  character  passes  through  to  the 
program. 

 ^^wj.^,  y  kju.  ouuuiu  execute: 

D  i:i  r   'i  L  C,  :    POKE.  106.0 

after  INKEY$  has  received  the  last  character 
you  want  from  a  soft  key  string.  This  POKE  is 
not  required  in  Disk  or  Advanced  BASIC. 


Example:   The  following  section  of  a  program  stops  the 

program  until  any  key  on  the  keyboard  is  pressed: 

1  10    PR  !  NT    "Prvs  .    -irr,    kt-\     !       oml  i  imk<; 
1/0   4    ( f*KF  v  >  :    I  V   h-}--'"-   J  H  F.  N  120 

The  next  example  shows  program  lines  that  could  be 
used  to  test  a  two-character  code  being  returned: 

220    I  f  LEIN  t'KB$  I-2  THEN   KB  $  -  R  !  G-u  J  $  ■  KB  T  .  ' 
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INP 
Function 


Purpose:     Returns  the  byte  read  from  port  n. 


Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:      v  =  INP(>?) 


Remarks:   n  must  be  in  the  range  0  to  65  5  35  - 

INP  is  the  complementary  function  to  the  OUT 
statement  (see  "OUT  Statement"  in  this  chapter). 

INP  performs  the  same  function  as  the  IN 
instruction  in  assembly  language.  Refer  to  the  IBM 
Personal  Computer  Technical  Reference  manual  for  a 
description  of  valid  port  numbers  (I/O  addresses). 


Example: 


00 


I  UP  i  255 


This  instruction  reads  a  byte  from  port  255  and 
assigns  it  to  the  variable  A. 
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INPUT 
Statement 


Purpose:     Receives  input  from  the  keyboard  during  program 
execution. 


Versions:    Cassette     Disk      Advanced  Compiler 


Format:      lNPUT[;]["prompt";]  variable[,variable\, 


Remarks:  "prompt' 


is  a  string  constant  which  will  be  used  to 
prompt  for  the  desired  input. 


4-122 


variable    is  the  name  of  the  numeric  or  string 

variable  or  array  element  which  will  receive 
the  input. 

When  the  program  sees  an  INPUT  statement,  it 
pauses  and  displays  a  question  mark  on  the  screen  to 
indicate  that  it  is  waiting  for  data.  If  a  "prompt"  is 
included,  the  string  is  displayed  before  the  question 
mark.  You  may  then  enter  the  required  data  from 
the  keyboard. 

You  may  use  a  comma  instead  of  a  semicolon  after 
the  prompt  string  to  suppress  the  queestion  mark. 
For  example,  the  statement  INPUT  "ENTER 
BIRTHDATE",B$  prints  the  prompt  without  the 
question  mark. 

The  data  that  you  enter  is  assigned  to  the  variable(s) 
given  in  the  variable  list.  The  data  items  you  supply 
must  be  separated  by  commas,  and  the  number  of 
data  items  must  be  the  same  as  the  number  of 
variables  in  the  list. 

The  type  of  each  data  item  that  you  enter  must  agree 
with  the  type  specified  by  the  variable  name.  (Strings 
entered  in  response  to  an  INPUT  statement  need 
not  be  surrounded  by  quotation  marks  unless  they 


INPUT 
Statement 


contain  commas  or  significant  leading  or  trailing 
blanks.) 

If  you  respond  to  INPUT  with  too  many  or  too  tew 
items,  or  with  the  wrong  type  of  value  (letters 
instead  of  numbers,  etc.),  BASIC  displays  the 
message  "?Redo  from  start".  If  a  single  variable  is 
requested,  you  may  simply  press  Enter  to  indicate 
the  default  values  of  0  for  numeric  input  or  null  for 
string  input.  However,  if  more  than  one  variable  is 
requested,  pressing  Enter  will  cause  the  "?Redo 
from  start"  message  to  be  printed  because  too  few 
items  were  entered.  BASIC  does  not  assign  any  of  the 
input  values  to  variables  until  you  give  an  acceptable 
response. 


Example: 


In  Disk  and  Advanced  BASIC,  if  INPUT  is 
immediately  followed  by  a  semicolon,  then  pressing 
Enter  to  input  data  does  not  produce  a  carriage 
return/line  feed  sequence  on  the  screen.  This  means 
that  the  cursor  remains  on  the  same  line  as  your 
response. 


In  this  example,  the  question  mark  displayed  by  the 
computer  is  a  prompt  to  tell  you  it  wants  you  to  enter 
something.  Suppose  you  enter  a  5.  The  program 
continues: 
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INPUT 
Statement 


Ok 

20    INPUT  "WHAT    IS    THE   RADIUS"; R 
30  t\~  P  i    R"  2 

'(0  PRINT   "THE  ARE.. \  OF  THE   CIRCLE  !:>";/. 

50  END 

RUN 

WHAT    IS    THE   RAD  I  US  ? 

For  this  second  example,  a  prompt  was  included  in 
line  20,  so  this  time  the  computer  prompts  with 
"WHAT  IS  THE  RADIUS?  "  Suppose  you  respond 
with  7.4.  The  program  continues: 


WHA F    IS   THE  RADIUS?      /  .  S 

i  HE  ,\RLm  OE    THE  C  !  RCLE    IS    1/1  .9^64 

•JR 
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INPUT  # 
Statement 


urpose:     Reads  data  items  from  a  sequential  device  or  file  and 
assigns  them  to  program  variables. 


Versions:  Cassette 
*** 


Disk 


Advanced 
*  *  * 


Compiler 


Format:      INPUT  #filenum,  variable  [,variable]... 


Remarks:  filenum 


is  the  number  used  when  the  file  was 
opened  for  input. 


variable    is  the  name  of  a  variable  that  will  have  an 
item  in  the  file  assigned  to  it.  It  may  be  a 
string  or  numeric  variable,  or  an  array 
element. 

The  sequential  file  may  reside  on  diskette  or  on 
cassette;  it  may  be  a  sequential  data  stream  from  a 
communications  adapter;  or  it  may  be  the  keyboard 
(KYBD:). 

The  type  of  data  in  the  file  must  match  the  type 
specified  by  the  variable  name.  Unlike  INPUT,  no 
question  mark  is  displayed  with  INPUT  #. 

The  data  items  in  the  file  should  appear  just  as  they 
would  if  the  data  were  being  typed  in  response  to  an 
INPUT  statement.  With  numeric  values,  leading 
spaces,  carriage  returns,  and  line  feeds  are  ignored. 
The  first  character  encountered  that  is  not  a  space, 
carriage  return,  or  line  feed  is  assumed  to  be  the  start 
of  the  number.  The  number  ends  with  a  space, 
carriage  return,  line  feed,  or  comma. 
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INPUT  # 
Statement 


If  BASIC  is  scanning  the  data  for  a  string  item, 
leading  spaces,  carriage  returns,  and  line  feeds  are 
also  ignored.  The  first  character  encountered  that  is 
not  a  space,  carriage  return,  or  line  feed  is  assumed 
to  be  the  start  of  the  string  item.  If  this  first  character 
is  a  quotation  mark  ("),  the  string  item  will  consist  of 
all  characters  read  between  the  first  quotation  mark 
and  the  second.  Thus,  a  quoted  string  may  not 
contain  a  quotation  mark  as  a  character.  If  the  first 
character  of  the  string  is  not  a  quotation  mark,  the 
string  is  an  unquoted  string;  it  will  end  when  a 
comma,  carriage  return,  or  line  feed,  or  after  255 
characters  have  been  read.  If  end  of  file  is  reached 
when  a  numeric  or  string  item  is  being  input,  the 
item  is  cancelled. 

INPUT  #  can  also  be  used  with  a  random  file. 

Example:   See  "Appendix  B.  BASIC  Diskette  Input  and 
Output." 
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INPUT$ 
Function 


Purpose:     Returns  a  string  of  n  characters,  read  from  the 
keyboard  or  from  file  number  filenum. 


Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:     v$  =  INPUT$(»  [,[#]/}/(?»*/»]) 


Remarks:   n  is  the  number  of  characters  to  be  read  from 

the  file. 

filenum     is  the  file  number  used  on  the  OPEN 
statement.  If  filenum  is  omitted,  the 
keyboard  is  read. 

If  the  keyboard  is  used  for  input,  no  characters  will 
be  displayed  on  the  screen.  All  characters  (including 
control  characters)  are  passed  through  except 
Ctrl-Break,  which  is  used  to  interrupt  the  execution 
of  the  INPUTS  function.  When  responding  to 
INPUTS  from  the  keyboard,  it  is  not  necessary  to 
press  Enter. 

The  INPUTS  function  enables  you  to  read 
characters  from  the  keyboard  which  are  significant 
to  the  BASIC  program  editor,  such  as  Backspace 
(ASCII  code  8).  If  you  want  to  read  these  special 
characters,  you  should  use  INPUTS  or  INKEY$  {not 
INPUT  or  LINE  INPUT). 

For  communications  files,  the  INPUTS  function  is 
preferred  over  the  INPUT  #  and  LINE  INPUT  # 
statements,  since  all  ASCII  characters  may  be 
significant  in  communications.  Refer  to  "Appendix 
F.  Communications." 
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INPUT$ 
Function 

Example:   The  following  program  lists  the  contents  of  a 
sequential  file  in  hexadecimal. 


10  OPEN   "DATA"  FOR   INPUT  AS  1 

20   I F  EOF  (  1  J   THEN  50 

30  PRINT  H EX ?( ASC( INPUT $(1,"1))); 

'40  GOTO  20 

50  PRINT 

60  END 

The  next  example  reads  a  single  character  from  the 
keyboard  in  response  to  a  question. 


100  PRINT  "TYPE  P  TO  PROCEED  OR  S  TO  STOP 

110  X$=  I NPUT$ ( 1 ) 

120  IF  X$="P"  THEN  500 

130  IF  X$="S"  THEN  700  ELSE  100 
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INSTR 
Function 


Purpose:  Searches  for  the  first  occurrence  of  string  _y#  inx$ 
and  returns  the  position  at  which  the  match  is  found. 
The  optional  offset  n  sets  the  position  for  starting 
the  search  in  x$. 


Versions:  Cassette 
*** 


Disk      Advanced  Compiler 


Format:     v  =  lNSTR([n,]x$,y$) 


Remarks:  n 


is  a  numeric  expression  in  the  range  1  to 
255. 


x$,  y$      may  be  string  variables,  string  expressions 
or  string  constants. 

If/?>LEN(;t$),  oi\{x$  is  null,  or  \{y$  cannot  be  found, 
INSTR  returns  0.  \{y$  is  null,  INSTR  returns  n  (or  1 
if  n  is  not  specified). 

\{n  is  out  of  range,  an  "Illegal  function  call"  error  will| 
be  returned. 


Example:  Ok 

10  A$ 


1  ;ABC  DEB' 
20  B5  =  "B1 
30  PRINT   I N S T R ( A ^ , B $ ; 

RUN 

2  6 
Ok 


INSTR(4,A$,B$. 


This  example  searches  for  the  string  "B"  within  the 
string  "  ABCDEB".  When  the  string  is  searched  from 
the  beginning,  "B"  is  found  at  position  2;  when  the 
search  starts  at  position4,  "B"  is  found  at  position 6. 
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INT 

Function 


Purpose:     Returns  the  largest  integer  that  is  less  than  or  equal 
to  x. 


Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:     v  =  INT(jc) 


Remarks:  x    is  any  numeric  expression. 

This  is  called  the  "floor"  function  in  some  other 
programming  languages. 

See  the  FIX  and  CINT  functions,  which  also  return 
integer  values. 


Example:  Ok 

PRINT   I  NT ( 45  -  67 ) 
45 

Ok 

PRINT  INTf-2.89) 

-  -5 

Ok 

This  example  shows  how  INT  truncates  positive 
integers,  but  rounds  negative  numbers  upward  (in  a 
negative  direction). 
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KEY 
Statement 


Purpose:    Sets  or  displays  the  soft  keys. 


Versions:    Cassette     Disk      Advanced  Compiler 

***  (**) 


***  *** 


Format: 


KEY  n,  x$ 
KEY  LIST 
KEY  ON 
KEY  OFF 


Remarks:   n      is  the  function  key  number  in  the  range  1  to  10. 

x$    is  a  string  expression  which  will  be  assigned  to  i 
the  key.  (Remember  to  enclose  string  constant; 
in  quotation  marks.) 

The  KEY  statement  allows  function  keys  to  be 
designated  soft  keys.  That  is,  you  can  set  each 
function  key  to  automatically  type  any  sequence  of  I 
characters.  A  string  of  up  to  15  characters  may  be  [ 
assigned  to  any  one  or  all  of  the  ten  function  keys. 
When  the  key  is  pressed,  the  string  will  be  input  to 
BASIC. 

Initially,  the  soft  keys  are  assigned  the  following 
values: 


Fl 

LIST 

F2 

RUN-«- 

F3 

LOAD" 

F4 

SAVE" 

F5 

CONT  CI- 

F6 

,"LPTl:"-»- 

F7 

TRON 

F8 

TROFF-*- 

F9 

KEY 

F10 

SCREEN  0,0,0-*- 

The  arrow        )  indicates  Enter. 
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KEY 

Statement 


KEY  ON  causes  the  soft  key  values  to  be  displayed 
on  the  25  th  line.  When  the  width  is  40,  five  of  the  ten 
soft  keys  are  displayed.  When  the  width  is  80,  all  ten 
are  displayed.  In  either  width,  only  the  first  six 
characters  of  each  value  are  displayed.  ON  is  the 
default  state  for  the  soft  key  display. 

KEY  OFF  erases  the  soft  key  display  from  the  25  th 
line,  making  that  line  available  for  program  use.  It 
does  not  disable  the  function  keys. 

KEY  LIST  lists  all  ten  soft  key  values  on  the  screen. 
All  15  characters  of  each  value  are  displayed. 

KEY/z,  x$  assigns  the  value  oix$  to  the  function  key 
specified  (1  to  10).  x$  may  be  1  to  15  characters  in 
length.  If  it  is  longer  than  1 5  characters,  only  the  first 
15  characters  are  assigned. 

Assigning  a  null  string  (string  of  length  zero)  to  a  soft 
key  disables  the  function  key  as  a  soft  key. 

If  the  value  entered  for#  is  not  the  range  1  to  10,  an 
"Illegal  function  call"  error  occurs.  The  previous 
key  string  assignment  is  retained. 

When  a  soft  key  is  pressed,  the  INKEY$  function 
returns  one  character  of  the  soft  key  string  each  time 
it  is  called.  If  the  soft  key  is  disabled,  INKEY$ 
returns  a  two  character  string.  The  first  character  is 
binary  zero,  the  second  is  the  key  scan  code,  as  listed 
in  "Appendix  G.  ASCII  Character  Codes." 
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KEY 
Statement 


Note:    To  avoid  complications  on  the  input 
buffer  in  Cassette  BASIC,  you  should  execute: 

DEF  SEG:   POKE  106,0 

after  reassigning  any  soft  keys  and  after 
INKEY$  has  received  the  last  character  you 
want  from  a  soft  key  string.  This  POKE  is  not 
required  in  Disk  or  Advanced  BASIC. 

After  turning  off  the  soft  key  display  with  KEY 
OFF,  you  can  use  LOCATE  25 , 1  followed  by  PRINT 
to  display  anything  you  want  on  the  bottom  line  of 
the  screen.  Information  on  line  25  is  not  scrolled,  as 
are  lines  1  through  24. 

See  the  following  section,  "KEY(n)  Statement,"  to 
see  how  to  enable  and  disable  function  key  trapping 
in  Advanced  BASIC. 


Example:    50  KEY  ON 

displays  the  soft  keys  on  the  25  th  line. 

200   KEY  OFF 

erases  soft  key  display.  The  soft  keys  are  still  active, 
but  not  displayed. 

10  KEY   1 , "Fl LES"+CHR$ ( 13) 

assigns  the  string  "FILES"+Enter  to  soft  key  1.  This 
is  a  way  to  assign  a  commonly  used  command  to  a 
function  key. 

20   KEY    1  ,  1111 

disables  function  key  1  as  a  soft  key. 
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KEY(n) 
Statement 


Purpose:     Activates  and  deactivates  trapping  of  the  specified 
key  in  a  BASIC  program.  See  "ON  KEY(n) 
Statement"  in  this  chapter. 


Versions:    Cassette     Disk      Advanced  Compiler 

***  (**) 


Format:      KEY(»)  ON 
KEY(»)  OFF 
KEY(«)  STOP 


Remarks:   n      is  a  numeric  expression  in  the  range  1  to  14,  and 
indicates  the  key  to  be  trapped: 

1-10  function  keys  Fl  to  F10 

11  Cursor  Up 

12  Cursor  Left 

13  Cursor  Right 

14  Cursor  Down 

KEY(tf)  ON  must  be  executed  to  activate  trapping 
of  function  key  or  cursor  control  key  activity.  After 
KEY(tf)  ON,  if  a  non-zero  line  number  was  specified 
in  the  ON  KEY(»)  statement  then  every  time  BASIC 
starts  a  new  statement  it  will  check  to  see  if  the 
specified  key  was  pressed.  If  so  it  will  perform  a 
GOSUB  to  the  line  number  specified  in  the  ON 
KEY(tf)  statement. 
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KEY(n) 
Statement 


If  KEY(z?)  is  OFF,  no  trapping  takes  place  and  even  if 
the  key  is  pressed,  the  event  is  not  remembered. 

Once  a  KEY(/z)  STOP  statement  has  been  executed, 
no  trapping  will  take  place.  However,  if  you  press 
the  specified  key  your  action  is  remembered  so  that 
an  immediate  trap  takes  place  when  KEY(«)  ON  is 
executed. 

KEY  (»)  ON  has  no  effect  on  whether  the  soft  key 
values  are  displayed  at  the  bottom  of  the  screen. 

If  you  use  a  KEY(/?)  statement  in  Cassette  or  Disk 
BASIC,  you  will  get  a  "Syntax  error."  Refer  to  the 
previous  section,  "KEY  Statement,"  for  an 
explanation  of  the  KEY  statement  without  the  (n). 


H 
> 

m 
Z 

C/3 
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KILL 
Command 


Purpose:     Deletes  a  file  from  a  diskette.  The  KILL  .command 
in  BASIC  is  similar  to  the  ERASE  command  in  DOS. 


Versions:    Cassette     Disk      Advanced  Compiler 

***  ***  *** 


Format:     KILL  filespec 

Remarks:  filespec     is  a  valid  file  specification  as  explained 
under  "Naming  Files"  in  Chapter  3.  The 
device  name  must  be  a  diskette  drive.  If 
the  device  name  is  omitted,  the  DOS 
default  drive  is  used. 

KILL  can  be  used  for  all  types  of  diskette  files.  The 
name  must  include  the  extension,  if  one  exists.  For 
example,  you  may  save  a  BASIC  program  using  the 
command 

SAVE  "TEST11 

BASIC  supplies  the  extension  .BAS  for  the  SAVE 
command,  but  not  for  the  KILL  command.  If  you 
want  to  delete  that  program  file  later,  you  must  say 
KILL  "TEST.BAS",  not  KILL  "TEST". 

If  a  KILL  statement  is  given  for  a  file  that  is 
currently  open,  a  "File  already  open"  error  occurs. 

Example:    200  KILL  "A:  DAT  A 1" 

This  example  deletes  the  file  named  "DATAl"  on 
drive  A:. 
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LEFT$ 
Function 


Purpose:     Returns  the  leftmost  n  characters  of  x$ 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      v$  =  LEFT$(x$,n) 


Remarks:  x$    is  any  string  expression. 

n      is  a  numeric  expression  which  must  be  in  the 
range  0  to  255.  It  specifies  the  number  of 
characters  which  are  to  be  in  the  result. 

If  n  is  greater  than  LEN(jt#),  the  entire  string  (x$)  is 
returned.  If  «=0,  the  null  string  (length  zero)  is 
returned. 

Also  see  the  MID$  and  RIGHTS  functions. 


Example:  Ok 


10  A$  =  "BAS I C  PROGRAM1 

20  B$  =  LEFT$(A$,5) 

30  PRINT  B^ 

RUN 

BAS  I  C 

Ok 


In  this  example,  the  LEFT$  function  is  used  to 
extract  the  first  five  characters  from  the  string 
"BASIC  PROGRAM". 
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LEN 

Function 


Purpose:     Returns  the  number  of  characters  inx$. 

Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:     v  =  LEN(*#) 

Remarks:  x$  is  any  string  expression. 

Unprintable  characters  and  blanks  are  included  in 
the  count  of  the  number  of  characters. 


Example:    10  X$  =  "BOCA  RATON ,  FLn 
20  PRINT  LEN(X$) 
RUN 

\k 
Ok 

There  are  14  characters  in  the  string  "BOCA 
RATON,  FL",  because  the  comma  and  the  blank  are 
counted. 
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LET 
Statement 


Purpose:     Assigns  the  value  of  an  expression  to  a  variable. 

Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:      [LET]  variable=expression 


Remarks:   variable    is  the  name  of  the  variable  or  array  element 
which  is  to  receive  a  value.  It  may  be  a 
string  or  numeric  variable  or  array 
element. 

expression  is  the  expression  whose  value  will  be 
assigned  to  variable.  The  type  of  the 
expression  (string  or  numeric)  must  match 
the  type  of  the  variable,  or  a  "Type 
mismatch"  error  will  occur. 

The  word  LET  is  optional,  that  is,  the  equal  sign  is 
sufficient  when  assigning  an  expression  to  a  variablej 
name. 
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LET 

Statement 


Example:    110  LET  DOR  1  =  12. 

!20   LET  E=D0R I +2 

130   LET   F'DANCE$  =  "HORA" 

This  example  assigns  the  value  12  to  the  variable 
DORI.  It  then  assigns  the  value  14,  which  is  the  value 
of  the  expression  DORI+2,  to  the  variable  E.  The 
string  "HORA"  is  assigned  to  the  variable 
FDANCE$. 

The  same  statements  could  have  also  been  written: 

110  DORI-  12 

120  E  -DORI+2 

130  FDANCES  -  "HORA" 
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LINE 
Statement 


Purpose:     Draws  a  line  or  a  box  on  the  screen. 


Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  *** 


Graphics  mode  only. 


Format:      LINE  [{xl,yl)}  \x2,y2)  [.[color]  [,B[F\]] 


Remarks:   (xl,yl),  (x2,y2) 

are  coordinates  in  either  absolute  or 
relative  form.  (See  "Specifying 
Coordinates"  under  "Graphics  Modes"  in 
Chapter  3-) 

color  is  the  color  number  in  the  range  0  to  3.  In 
medium  resolution,  color  selects  the  color 
from  the  current  palette  as  defined  by  the 
COLOR  statement.  0  is  the  background 
color.  The  default  is  the  foreground  color, 
color  number  3-  In  high  resolution,  a  color 
of  0  (zero)  indicates  black,  and  the  default 
of  1  (one)  indicates  white. 

The  simplest  form  of  LINE  is: 

LINE  -(X2,Y2) 

This  will  draw  a  line  from  the  last  point  referenced 
to  the  point  (X2,Y2)  in  the  foreground  color. 
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LINE 
Statement 


We  can  include  a  starting  point  also: 

LINE   (0 ,0) - (319, 199)    'diagonal   down  screen 
LINE   (0 , 100) - (319, 100)    'bar  across  screen 

We  can  indicate  the  color  to  draw  the  line  in: 

LINE   (10, 10) -(20,20) ,2   'draw   in  color  2 

1    'draw  random  lines    in   random  colors 

10  SCREEN   1 ,0,0,0:  CLS 

20  LINE  -(RND-'-319,RND-'-199)  ,RND-'^ 

30  GOTO  20 

1    'alternating  pattern  -   line  on,    line  off 

10  SCREEN   1,0,0,0:  CLS 

20  FOR  X=0  TO  319 

30  LINE   (X,0)-(X, 199) ,X  AND  1 

^0  NEXT 

The  last  argument  to  LINE  is  B  -  box,  or  BF  -  filled 
box.  We  can  leave  out  color  and  include  the  final 
argument: 

LINE    (0,0)-(l00, 100) , ,B    'box  in  foreground 

or  we  may  include  the  color: 

LINE    (0,0)-(l00,100)  ,2,BF   'fill   box  color  2 

The  B  tells  BASIC  to  draw  a  rectangle  with  the 
points  (xl,yl)  and  (x2,y2)  as  opposite  corners.  This 
avoids  having  to  give  the  four  LINE  commands: 

LINE  (X1 , Y1 ) - (X2  ,Y1 ) 

LINE  (XI ,Y1)-(X1 ,Y2) 

LINE  (X2 ,Y1 ) - (X2 ,Y2) 

LINE  (X1 ,Y2) -(X2.Y2) 

which  perform  the  equivalent  function. 
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LINE 
Statement 


The  BF  means  draw  the  same  rectangle  as  B,  but  also 
fill  in  the  interior  points  with  the  selected  color. 

When  coordinates  which  are  out  of  range  are  given 
to  the  LINE  statement,  the  coordinate  which  is  out 
of  range  is  given  the  closest  valid  value.  In  other 
words,  the  negative  values  become  zero  and  Y  values 
greater  than  199  become  199-  X  values  greater  than 
639  become  639.  X  values  greater  than  319  in 
medium  resolution  wrap  to  the  next  horizontal  line. 

The  last  point  referenced  after  a  LINE  statement  is 
point  (x2,y2).  If  you  use  the  relative  form  for  the 
second  coordinate,  it  is  relative  to  the  first 
coordinate.  For  example, 

LINE   ( 100 , 100) -STEP  (10,-20) 
will  draw  a  line  from  (100,100)  to  (1 10,80). 


Example:    This  example  will  draw  random  filled  boxes  in 
random  colors. 

10  CLS 

20  SCREEN   1 ,0:    COLOR  0,0 

30  LINE  -  (  RN  D  3  1 9  ,  RN  D  -  :  1  99  )  ,  RN  D  2  +  1  ,  B  F 

40  GOTO  30    'boxes  will  overlap 
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Purpose:     Reads  an  entire  line  (up  to  254  characters)  from  the 
keyboard  into  a  string  variable,  ignoring  delimiters. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:     LINE  INPUT[;]["prompt"\]  stringvar 


Remarks:  "prompt' 


is  a  string  constant  that  is  displayed  on  the 
screen  before  input  is  accepted.  A 
question  mark  is  not  printed  unless  it  is 
part  of  the  prompt  string. 


stringvar  is  the  name  of  the  string  variable  or  array 
element  to  which  the  line  will  be  assigned. 
All  input  from  the  end  of  the  prompt  to 
the  Enter  is  assigned  to  stringvar.  Trailing 
blanks  are  ignored. 

In  Disk  and  Advanced  BASIC,  if  LINE  INPUT  is 
immediately  followed  by  a  semicolon,  then  pressing 
Enter  to  end  the  input  line  does  not  produce  a 
carriage  return/line  feed  sequence  on  the  screen. 
That  is,  the  cursor  remains  on  the  same  line  as  your 
response. 

You  can  exit  LINE  INPUT  by  pressing  Ctrl-Break 
RA<JTr   
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LINE  INPUT  # 
Statement 


Purpose:     Reads  an  entire  line  (up  to  254  characters),  ignoring 
delimiters,  from  a  sequential  file  into  a  string 
variable. 


Versions: 


Cassette 
*** 


Disk 
*  *  * 


Advanced 
*** 


Compiler 


Format:      LINE  INPUT  #filenum,  stringvar 


Remarks:  filenum     is  the  number  under  which  the  file  was 
opened. 

stringvar  is  the  name  of  a  string  variable  or  array 
element  to  which  the  line  will  be  assigned. 

LINE  INPUT  #  reads  all  characters  in  the  sequential 
file  up  to  a  carriage  return.  It  then  skips  over  the 
carriage  return/line  feed  sequence,  and  the  next 
LINE  INPUT  #  reads  all  characters  up  to  the  next 
carriage  return.  (If  a  line  feed/carriage  return 
sequence  is  encountered,  it  is  preserved.  That  is,  the 
line  feed/carriage  return  characters  are  returned  as 
part  of  the  string.) 

LINE  INPUT  #  is  especially  useful  if  each  line  of  a 
file  has  been  broken  into  fields,  or  if  a  BASIC 
program  saved  in  ASCII  mode  is  being  read  as  data 
by  another  program. 

LINE  INPUT  #  can  also  be  used  for  random  files. 
See  "Appendix  B.  BASIC  Diskette  Input  and 
Output." 
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LINE  INPUT  # 
Statement 


Example:   The  following  example  uses  LINE  INPUT  to  get 
information  from  the  keyboard,  where  the 
information  is  likely  to  have  commas  or  other 
delimiters  in  it.  Then  the  information  is  written  to  a 
sequential  file,  and  read  back  out  from  the  file  using 
LINE  INPUT  #. 

Ok 

10  OPEN  "LIST"  FOR  OUTPUT  AS  1 
20  LINE    INPUT  "Address?  ";C$ 
30  PR  I  NT  ■- 1  ,  C$ 
'4  0  CLOSE  I 

50  OPEN  "LIST"  FOR   ! NPUT  AS    -  1 

60  LINE   INPUT  --I,  C$ 

70  PRINT  C$ 

80  CLOSE  ! 

RUN 


Suppose  you  respond  with  DELRAY  BEACH,  FL 
33445.  The  program  continues: 

d  '-e-..  '.>'.    OELRAV   BEACH,    P  L  33^5 
DP  CRAY   BEACH  ,   PL  33^5 
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LIST 
Command 


Purpose:     Lists  the  program  currently  in  memory  on  the 
screen  or  other  specified  device. 


Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  *** 


Format:      LIST  [linel]  [-[line2]\  [filespec] 


Remarks:  linel,  line2 

are  valid  line  numbers  in  the  range  0  to 
65529.  linel  is  the  first  line  to  be  listed. 
Iine2  is  the  last  line  to  be  listed.  A  period  (.) 
may  be  used  for  either  line  number  to 
indicate  the  current  line. 


filespec     is  a  string  expression  for  the  file 

specification  as  outlined  under  "Naming 
Files"  in  Chapter  3.  If  filespec  is  omitted, 
the  specified  lines  are  listed  on  the  screen. 

In  Cassette  BASIC,  listings  directed  to  the  screen  by 
omitting  the  device  specifier  may  be  stopped  at  any 
time  by  pressing  Ctrl-Break.  Listings  directed  to 
specific  devices  may  not  be  interrupted,  and  will  list 
until  the  range  is  exhausted.  That  is,  LIST  range  may 
be  interrupted,  but  LIST  range,  "SCRN:"  may  not. 

In  Disk  and  Advanced  BASIC,  any  listing  to  either 
the  screen  or  the  printer  may  be  interrupted  by 
pressing  Ctrl-Break. 

If  the  line  range  is  omitted,  the  entire  program  is 
listed. 
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LIST 

Command 


When  the  dash  (-)  is  used  in  a  line  range,  three 
options  are  available: 

•  If  only  linel  is  given,  that  line  and  all  higher 
numbered  lines  are  listed. 

•  If  only  line2  is  given,  all  lines  from  the  beginning 
of  the  program  through  Une2  are  listed. 

•  If  both  line  numbers  are  specified,  all  lines  from 
linel  through  line2,  inclusive,  are  listed. 

When  you  list  to  a  file  on  cassette  or  diskette,  the 
specified  part  of  the  program  is  saved  in  ASCII 
format.  This  file  may  later  be  used  with  MERGE. 

Example:    L  !  S  T 

Lists  the  entire  program  on  the  screen. 

LIST   35 , "SCRN  :  " 

Lists  line  35  on  the  screen. 

LIST   10-20,   1  'LPT  1  :" 

Lists  lines  10  through  20  on  the  printer. 

LIST   100-    ,  !  'COM  1  :  1  200  ,N  ,8" 

Lists  all  lines  from  100  through  the  end  of  the 
program  to  the  first  communications  adapter  at 
1200  bps,  no  parity,  8  data  bits,  1  stop  bit. 

L  !  ST   -200 , "CAS  1  :  BOB" 

Lists  from  the  first  line  through  line  200  to  a  file 
named  "BOB"  on  cassette. 
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LLIST 
Command 


purpose:     Lists  all  or  part  of  the  program  currently  in  memory 
on  the  printer  (LPTl:). 

Versions:    Cassette     Disk      Advanced  Compiler 


Format:      LLIST  \linel\\-  [line2}\ 


Remarks:   The  line  number  ranges  for  LLIST  work  the  same  as 
for  LIST. 

In  Cassette  BASIC,  LLIST  cannot  be  interrupted  by 
Ctrl-Break.  If  you  want  to  stop  the  list,  you  must 
turn  the  printer  off. 

BASIC  always  returns  to  command  level  after  an 
LLIST  is  executed. 


Example: 

Prints  a  listing  of  the  entire  program. 
Prints  line  35. 


Lists  lines  10  through  20  on  the  printer. 

LLIST  100- 

Prints  all  lines  from  100  through  the  end  of  the 
program. 

LLIST  -230 

Prints  the  first  line  through  line  200. 
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LOAD 
Command 


Purpose:     Loads  a  program  from  the  specified  device  into 
memory,  and  optionally  runs  it. 


Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  *** 


Format:  LOADfi/espec[,R] 


Remarks:  filespec     is  a  string  expression  for  the  file 

specification.  It  must  conform  to  the  rules 
outlined  under  "Naming  Files"  in  Chapter 
3,  otherwise  an  error  occurs  and  the  load  is 
cancelled. 

LOAD  closes  all  open  files  and  deletes  all  variables 
and  program  lines  currently  residing  in  memory 
before  it  loads  the  specified  program.  If  the  R 
option  is  omitted,  BASIC  returns  to  direct  mode 
after  the  program  is  loaded. 

However,  if  the  R  option  is  used  with  LOAD,  the 
program  is  run  after  it  is  loaded.  In  this  case  all  open 
data  files  are  kept  open.  Thus,  LOAD  with  the  R 
option  may  be  used  to  chain  several  programs  (or 
segments  of  the  same  program).  Information  may 
be  passed  between  the  programs  using  data  files. 

LOAD  filespec^  is  equivalent  to  RUN  filespec. 

If  you  are  using  Cassette  BASIC  and  the  device  name 
is  omitted,  CASl:  is  assumed.  CASl:  is  the  only 
allowable  device  for  LOAD  in  Cassette  BASIC. 
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LOAD 
Command 


If  you  are  using  Disk  or  Advanced  BASIC,  the  DOS 
default  diskette  drive  is  used  if  the  device  is  omitted. 
The  extension  .BAS  is  added  to  the  filename  if  no 
extension  is  supplied  and  the  filename  is  eight 
characters  or  less. 


Notes  when  using  CASl: 

1.     If  the  LOAD  statement  is  entered  in  direct 
mode,  the  file  names  on  the  tape  will  be 
displayed  on  the  screen  followed  by  a  period  (.) 
and  a  single  letter  indicating  the  type  of  file. 
This  is  followed  by  the  message  "Skipped."  for 
the  files  not  matching  the  named  file,  and 
"Found."  when  the  named  file  is  found.  Types 
of  files  and  their  corresponding  letter  are: 


.B    for  BASIC  programs  in  internal  format 

(created  with  SAVE  command) 
.P    for  protected  BASIC  programs  in  internal 

format  (created  with  SAVE  ,P  command) 
.A    for  BASIC  programs  in  ASCII  format 

(created  with  SAVE  ,A  command) 
.M    for  memory  image  files  (created  with 

BSAVE  command) 
.D    for  data  files  (created  by  OPEN  followed 

by  output  statements) 


To  see  what  files  are  on  a  cassette  tape,  rewind 
the  tape  and  enter  some  name  that  is  known  not 
to  be  on  the  tape.  For  example,  LOAD 
"CASl:NOWHERE".  All  file  names  will  then 
be  displayed. 


If  the  LOAD  command  is  executed  in  a  BASIC 
program,  the  file  names  skipped  and  found  are 
not  displayed  on  the  screen. 
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LOAD 
Command 


2.  Note  that  Ctrl-Break  may  be  typed  at  any  time 
during  LOAD.  Between  files  of  after  a  time-out 
period,  BASIC  will  exit  the  search  and  return  to 
command  level.  Previous  memory  contents 
remain  unchanged. 

3.  If  CASl:  is  specified  as  the  device  and  the 
filename  is  omitted,  the  next  program  file  on 
the  tape  is  loaded. 


Example:    LOAD  "MENU" 

Loads  the  program  named  MENU,  but  does  not  run 
it. 

LOAD  ' '  I NV ENT" , R 

Loads  and  runs  the  program  INVENT. 

RUN  "INVENT" 

Same  as  LOAD  "  INVENT", R. 

LOAD  "B: REPORT. B AS" 

Loads  the  file  REPORT.  BAS  from  diskette  drive  B. 
Note  that  the  .BAS  did  not  have  to  be  specified. 

LOAD  1  'CAS  1  :  " 

Loads  the  next  program  on  the  tape. 
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LOC 
Function 


Purpose:     Returns  the  current  position  in  the  file. 

Versions:    Cassette      Disk      Advanced  Compiler 

***  ***  *** 


Format:      v  =  hOCifilenum) 

Remarks:  filenum     is  the  file  number  used  when  the  file  was 
opened. 

With  random  files,  LOC  returns  the  record  number 
of  the  last  record  read  or  written  to  a  random  file. 

With  sequential  files,  LOC  returns  the  number  of 
records  read  from  or  written  to  the  file  since  it  was 
opened.  (A  record  is  a  1 28  byte  block  of  data.)  When 
a  file  is  opened  for  sequential  input,  BASIC  reads  the 
first  sector  of  the  file,  so  LOC  will  return  a  1  even 
before  any  input  from  the  file. 

For  a  communications  file,  LOC  returns  the  number 
of  characters  in  the  input  buffer  waiting  to  be  read. 
The  default  size  for  the  input  buffer  is  256 
characters,  but  you  can  change  this  with  the  /C: 
option  on  the  BASIC  command.  If  there  are  more 
than  255  characters  in  the  buffer,  LOC  returns  255. 
Since  a  string  is  limited  to  255  characters,  this 
practical  limit  alleviates  the  need  for  you  to  test  for 
string  size  before  reading  data  into  it.  If  fewer  than 
235  characters  remain  in  the  buffer,  then  LOC 
returns  the  actual  count. 
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LOG 
Function 

Example:    200  IF  L  0  C  ( 1  )   50  THEN  STOP 

This  first  example  stops  the  program  if  we've  gone 
past  the  50th  record  in  the  file. 

300  PUT     1  ,  LOC  (  1  ) 

The  second  example  could  be  used  to  re-write  the 
record  that  was  just  read. 
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LOCATE 
Statement 


Purpose:  Positions  the  cursor  on  the  active  screen.  Optional 
parameters  turn  the  Blinking  cursor  on  and  off  and 
define  the  size  of  the  blinking  cursor. 


Versions: 


Cassette 
*** 


Disk 
*  *  * 


Advanced 
*** 


Compiler 


Format:      LOCATE  [row][,[col\  [,[cursor][,[start]  [,stop]  ]]] 


Remarks:  row 


col 


cursor 


start 


stop 


is  a  numeric  expression  in  the  range  1  to 
25.  It  indicates  the  screen  line  number 
where  you  want  to  place  the  cursor. 

is  a  numeric  expression  in  the  range  1  to  40 
or  1  to  80,  depending  upon  screen  width.  It 
indicates  the  screen  column  number 
where  you  want  to  place  the  cursor. 

is  a  value  indicating  whether  the  cursor  is 
visible  or  not.  A  0  (zero)  indicates  off,  1 
(one)  indicates  on. 

is  the  cursor  starting  scan  line.  It  must  be  a 
numeric  expression  in  the  range  0  to  31. 

is  the  cursor  stop  scan  line.  It  also  must  be 
numeric  expression  in  the  range  0  to  31. 


cursor,  start  and  stop  do  not  apply  to  graphics  mode. 
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LOCATE 
Statement 


start  and  stop  allow  you  to  make  the  cursor  any  size 
you  want.  You  indicate  the  starting  and  ending  scan 
lines.  The  scan  lines  are  numbered  from  0  at  the  top 
of  the  character  position.  The  bottom  scan  line  is  7  if 
you  have  the  Color/Graphics  Monitor  Adapter,  1  3  if 
you  have  the  IBM  Monochrome  Display  and  Parallel 
Printer  Adapter.  If  start  is  given  and  stop  is  omitted, 
stop  assumes  the  value  of  start.  If  start  is  greater  than 
stop,  you'll  get  a  two-part  cursor.  The  cursor  "wraps" 
from  the  bottom  line  back  to  the  top. 

After  a  LOCATE  statement,  I/O  statements  to  the 
screen  begin  placing  characters  at  the  specified 
location. 

When  a  program  is  running,  the  cursor  is  normally 
off.  You  can  use  LOCATE  „1  to  turn  it  back  on. 

Normally,  BASIC  will  not  print  to  line  25.  However, 
you  can  turn  off  the  soft  key  display  using  KEY 
OFF,  then  use  LOCATE  25,1:  PRINT...  to  put 
things  on  line  25. 

Any  parameter  may  be  omitted.  Omitted  parameters 
assume  the  current  value. 

Any  values  entered  outside  of  the  ranges  indicated 
will  result  in  an  "Illegal  function  call"  error.  Previous 
values  are  retained. 
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LOCATE 
Statement 


Example:    10  LOCATE  1,1 

Moves  the  cursor  to  the  home  position  in  the  upper 
left-hand  corner  of  the  screen. 

20  LOCATE   , , 1 

Makes  the  blinking  cursor  visible;  its  position 
remains  unchanged. 

30  LOCATE   , , ,7 

Position  and  cursor  visibility  remain  unchanged. 
Sets  the  cursor  to  display  at  the  bottom  of  the 
character  on  the  Color/Graphics  Monitor  Adapter 
(starting  and  ending  on  scan  line  7). 


LOCATE  5,1,1,0,7 


Moves  the  cursor  to  line  5,  column  1.  Makes  the 
cursor  visible,  covering  the  entire  character  cell  on 
the  Color/Graphics  Monitor  Adapter,  starting  at 
scan  line  0  and  ending  on  scan  line  7. 
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LOF 

Function 


Purpose:     Returns  the  number  of  bytes  allocated  to  the  file 
(length  of  the  file). 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      v  =  LOF(filenum) 


Remarks:  filenum 


is  the  file  number  used  when  the  file  was 
opened. 


For  diskette  files  created  by  BASIC,  LOF  will  return 
a  multiple  of  128.  For  example,  if  the  actual  data  in 
the  file  is  257  bytes,  the  number  384  will  be 
returned.  For  diskette  files  created  outside  BASIC 
(for  example,  by  using  EDLIN),  LOF  returns  the 
actual  number  of  bytes  allocated  to  the  file. 

For  communications,  LOF  returns  the  amount  of 
free  space  in  the  input  buffer.  That  is, 
size-LOC(fifenum),  where  size  is  the  size  of  the 
communications  buffer,  which  defaults  to  256  but 
may  be  changed  with  the  /C:  option  on  the  BASIC 
command.  Use  of  LOF  may  be  used  to  detect  when 
the  input  buffer  is  getting  full.  In  practicality,  LOC 
is  adequate  for  this  purpose,  as  demonstrated  in  the 
example  in  "Appendix  F.  Communications." 


Example:  These  statements  will  get  the  last  record  of  the  file 
named  BIG,  assuming  BIG  was  created  with  a  record 
length  of  128  bytes: 


i  0 

1  :  t 
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LOG 
Function 


Purpose: 
Versions: 


Format: 
Remarks: 


Example: 


Returns  the  natural  logarithm  of  x. 
Cassette      Disk      Advanced  Compiler 


x      must  be  a  numeric  expression  which  is  greater 
than  zero. 

The  natural  logarithm  is  the  logarithm  to  the  base  e. 


The  first  example  calculates  the  logarithm  of  the 
expression  45/7: 


The  second  example  calculates  the  logorithm  of  e 
and  of  e2  : 

Ok 

E-  2  .718282 
Ok 

?   LOG  IE) 


0  k. 


PRINT   LOG ( h^f 7 ) 
. 360752 


0 


Ok 

?   LOG  (  E  '"  E  ) 


Ok 
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LPOS 
Function 


Purpose:    Returns  the  current  position  of  the  print  head 
within  the  printer  buffer  for  LPTl:. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:     v  =  LPOS(») 


Remarks:   n      is  a  numeric  expression  which  is  a  dummy 
argument  in  Cassette  BASIC.  In  Disk  and 
Advanced  BASIC,  n  indicates  which  printer  is 
being  tested,  as  follows: 


0  or  1 

2 

3 


LPTl 
LPT2 
LPT3 


Therefore,  we  recommend  you  use  0  or  1  in  Cassette 
BASIC  to  maintain  compatibility  with  the  other 
versions. 

The  LPOS  function  does  not  necessarily  give  the 
physical  position  of  the  print  head  on  the  printer. 


Example:    In  this  example,  if  the  line  length  is  more  than  60 
characters  long  we  send  a  carriage  return  character 
to  the  printer  so  it  will  skip  to  the  next  line. 

100    IF  LPOS(0)  -60  THEN  LPRINT  CHR$ ( 1 3) 
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LPRINT  and  LPRINT  USING 

Statements 


Purpose:     Prints  data  on  the  printer  (LPTl:). 

Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:      LPRINT  [list  of  expressions]  [;] 

LPRINT  USING  v$;  list  of  expressions  [;] 

Remarks:   list  of  expressions 

is  a  list  of  the  numeric  and/or  string 
expressions  that  are  to  be  printed.  The 
expressions  must  be  separated  by  commas 
or  semicolons. 


v$  is  a  string  constant  or  variable  which 

identifies  the  format  to  be  used  for 
printing.  This  is  explained  in  detail  under 
"PRINT  USING  Statement." 

These  statements  function  like  PRINT  and  PRINT 
USING,  except  output  goes  to  the  printer.  See 
"PRINT  Statement"  and  "PRINT  USING 
Statement." 


LPRINT  assumes  an  80-character  wide  printer.  That 
is,  BASIC  automatically  inserts  a  carriage  return/line 
feed  after  printing  80  characters.  This  will  result  in 
two  lines  being  skipped  when  you  print  exactly  80 
characters,  unless  you  end  the  statement  with  a 
semicolon.  You  may  change  the  width  value  with  a 
WIDTH  "LPTl:"  statement. 


Printing  is  asynchronous  with  processing.  If  you  do 
a  form  feed  (LPRINT  CHR$(12);)  followed  by 
another  LPRINT  and  the  printer  takes  more  than  10 
seconds  to  do  the  form  feed,  you  may  get  a  "Device 
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LPRINT  and  LPRINT  USING 
Statements 


Timeout"  error  on  the  second  LPRINT.  To  avoid 
this  problem,  do  the  following: 

1   ON  ERROR  GOTO  65000 


65000    IF  ERR  -  2k  THEN  RESUME    '2*4=t  iine->ut 

You  might  want  to  test  ERL  to  make  sure  the 
timeout  was  caused  by  an  LPRINT  statement. 

Example:   This  is  an  example  of  sending  special  control 

characters  to  the  IBM  80  CPS  Matrix  Printer  using 
LPRINT  and  CHR$.  The  printer  control  characters 
are  listed  in  the  IBM  Personal  Computer  Technical 
Reference  manual. 

10  LPRI N 1    CHRS '  1      ; "  Title    Li ne' 

20  FOR    1-2    rO  k 

30  LPRI  NT   "Repor  t  line11: 

•4  0  NEXT 

50  LPRINT  CHRS  1  1  3  >  ;"C..rnlensfcd  prim;    1  '$2  ch.ir    ;  i  -<•' 

6f  LF'R  '•  NT   LHRS  M  8  ■  ; 1  'Ret  ..i  •)   t,,  rvu-;  ,\\  " 

70  LPRI  NT   CHRS ■ 2  /  )  ; "F" 

80  LPRI  NT   1  TP  1  ,    is  ei-nh.i-  1  /cd  dv  i  n  l 11 

90  LPRiNl    CHRSf  2/i  ;"FM 

1  (50   l  PRINT   1  'B.K.k    lc  nor  m  I    dqa  in" 

The  output  produced  by  this  program  looks  like 
this: 

T  i.  t:.  I.  e<     I.  i.  n 

Report  line  2 
Rep or  t  1 i  ne  3 
Report  I i ne  4 
Condensed  print;  132  char/line 

R  e  1 1.'  r  n   t  o  n  o  r  m  a  ,\. 

This  is  emphasized  print 

B  a  c  k   t  o  n  a  r  m  a  .1    a  q  a  i  n 
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LSET  and  RSET 
Statements 


Purpose:     Moves  data  into  a  random  file  buffer  (in  preparation 
for  a  PUT  (file)  statement). 

Versions:    Cassette      Disk      Advanced  Compiler 

***  ***  *** 

Format:      LSET  stringvar  =  x$ 
RSET  stringvar  =  x$ 


Remarks:   stringvar  is  the  name  of  a  variable  that  was  defined  in 
a  FIELD  statement. 

x$  is  a  string  expression  for  the  information 

to  be  placed  into  the  field  identified  by 
stringvar. 

If  x$  requires  fewer  bytes  than  were  specified  for 
stringvar  in  the  FIELD  statement,  LSET  left-justifies 
the  string  in  the  field,  and  RSET  right-justifies  the 
string.  (Spaces  are  used  to  pad  the  extra  positions.) 
\{x$  is  longer  than  stringvar,  characters  are  dropped 
from  the  right. 

Numeric  values  must  be  converted  to  strings  before 
they  are  LSET  or  RSET.  See  "MKI$,  MKS$,  MKD$ 
Functions"  in  this  chapter. 
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LSET  and  RSET 
Statements 


Refer  to  "Appendix  B.  BASIC  Diskette  Input  and 
Output"  for  a  complete  explanation  of  using 
random  files. 

Note:    LSET  or  RSET  may  also  be  used  with  a 
string  variable  which  was  not  defined  in  a 
FIELD  statement  to  left-justify  or  right-justify 
a  string  in  a  given  field.  For  example,  the 
program  lines: 

1 10  A$=SPACE$ (20) 
120  RSET  A$=N$ 

right-justify  the  string  N$  in  a  20-character 
field.  This  can  be  useful  for  formatting  printed 
output. 


Example:   This  example  converts  the  numeric  value  AMT  into 
a  string,  and  left-justifies  it  in  the  field  A$  in 
preparation  for  a  PUT  (file)  statement. 

150  LSET  A$=MKS  $ ( AMT) 
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MERGE 
Command 


Purpose:     Merges  the  lines  from  an  ASCII  program  file  into  the 
program  currently  in  memory. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  *** 


Format:     MERGE  filespec 

Remarks:  filespec     is  a  string  expression  for  the  file 

specification.  It  must  conform  to  the  rules 
for  naming  files  as  outlined  in  "Naming 
Files"  in  Chapter  3;  otherwise  an  error 
occurs  and  the  MERGE  is  cancelled. 

The  device  is  searched  for  the  named  file.  If  found, 
the  program  lines  in  the  device  file  are  merged  with 
the  lines  in  memory.  If  any  lines  in  the  file  being 
merged  have  the  same  line  number  as  lines  in  the 
program  in  memory,  the  lines  from  the  file  will 
replace  the  corresponding  lines  in  memory. 

After  the  MERGE  command,  the  merged  program 
resides  in  memory,  and  BASIC  returns  to  command 
level. 

In  Cassette  BASIC,  if  the  device  name  is  omitted, 
CASl:  is  assumed.  CASl:  is  the  only  allowable 
device  for  MERGE  in  Cassette  BASIC.  With  Disk 
and  Advanced  BASIC,  if  the  device  name  is  omitted, 
the  DOS  default  drive  is  assumed. 

If  CASl:  is  specified  as  the  device  name  and  the 
filename  is  omitted,  the  next  ASCII  program  file 
encountered  on  the  tape  is  merged. 
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MERGE 
Command 


If  the  program  being  merged  was  not  saved  in  ASCII 
format  (using  the  A  option  on  the  SAVE  command), 
a  "Bad  file  mode"  error  occurs.  The  program  in 
memory  remains  unchanged. 

Example:    MERGE  "A:NUMBRS" 

This  merges  the  file  named  "NUMBRS"  on  drive  A: 
with  the  program  in  memory. 
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MID$ 

Function  and  Statement 


Purpose:  Returns  the  requested  part  of  a  given  string.  When 
Versions:    Cassette      Disk      Advanced  Compiler 

#  #  *  *  sfr  *  *  *  * 


Format:      As  a  function: 

i$  =  MID$(x$,  7i[,m]) 
As  a  statement: 

MID$(v$,  n[,m])  =  y$ 

Remarks:   For  the  function  (v$=MID$...): 

x$     is  any  string  expression. 

n      is  an  integer  expression  in  the  range  1  to  255- 

m     is  an  integer  expression  in  the  range  0  to  255- 

The  function  returns  a  string  of  length  m  characters 
from  x$  beginning  with  the  nth.  character.  If  m  is 
omitted  or  if  there  are  fewer  than  m  characters  to  the 
right  of  the  »th  character,  all  rightmost  characters 
beginning  with  thewth  character  are  returned.  Ifw  is 
equal  to  zero,  or  if  n  is  greater  than  LEN(;t#),  then 
MID$  returns  a  null  string. 

Also  see  the  LEFT$  and  RIGHT$  functions. 
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MID$ 

Function  and  Statement 


For  the  statement  (MID$...=y$): 

v$     is  a  string  variable  or  array  element  that  will 
have  its  characters  replaced. 

n      is  an  integer  expression  in  the  range  1  to  255- 

m     is  an  integer  expression  in  the  range  0  to  255. 

y$    is  a  string  expression. 

The  characters  in  v$,  beginning  at  position  n,  are 
replaced  by  the  characters  iny$.  The  optional  m 
refers  to  the  number  of  characters  from>$  that  will 
be  used  in  the  replacement.  If  m  is  omitted,  all  oiy$ 
is  used. 

However,  regardless  of  whether  m  is  omitted  or 
included,  the  length  of  v$  does  not  change.  For 
example,  if  v$  is  four  characters  long  and_y$  is  five 
characters  long,  then  after  the  replacement  v$  will 
contain  only  the  first  four  characters  oiy$. 

Note:    If  either  n  or  m  is  out  of  range,  an 
"Illegal  function  call"  error  will  be  returned. 
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MID$ 

Function  and  Statement 


Example:   The  first  example  uses  the  MID$  function  to  select 
the  middle  portion  of  the  string  B$. 

Ok 

10  A$="G00D  ' 

20  B$=--'  'MORN  I  NG   EVENING  AFTERNOON11 

30   PRINT  A$ ; M I D$(B$,9,7) 

RUN 

GOOD  EVENING 
Ok 


The  next  example  uses  the  MID$  statement  to 
replace  characters  in  the  string  A$. 

Ok 

1  0  A$  =  '  'MARATHON  ,  GREECE" 
20  Ml  D$(A$  ,  1  1 )  ='  'FLOR  I  DA" 
30  PRINT  A$ 
RUN 

MARATHON ,  FLORID 
Ok 

Note  in  the  second  example  how  the  length  of  A$ 
was  not  changed. 
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MKI$,  MKS$,  MKD$ 
Functions 


Purpose:  Convert  numeric  type  values  to  string  type  values. 
Versions:    Cassette      Disk      Advanced  Compiler 


Format:      v$  =  MKI$  [integer  expression) 

v$  =  MKS$  [single-precision  expression) 
v$  =  MKD$  {double-precision  expression) 

Remarks:   Any  numeric  value  that  is  placed  in  a  random  file 
buffer  with  an  LSET  or  RSET  statement  must  be 
converted  to  a  string.  MKI$  converts  an  integer  to  a 
2-byte  string.  MKS$  converts  a  single-precision 
number  to  a  4-byte  string.  MKD$  converts  a 
double-precision  number  to  an  8-byte  string. 

These  functions  differ  from  STR$  in  that  they  do 
not  actually  change  the  bytes  of  the  data,  just  the 
way  BASIC  interprets  those  bytes. 

See  also  "CVI,  CVS,  CVD  Functions"  in  this  chapter 
and  "Appendix  B.  BASIC  Diskette  Input  and 
Output." 
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MKI$,  MKS$,  MKD$ 
Functions 


Example:    This  example  uses  a  random  file  (#1)  with  fields 

defined  in  line  100.  The  first  field,  D$,  is  intended  to 
hold  a  numeric  value,  AMT.  Line  110  converts  AMT 
to  a  string  value  using  MKS$  and  uses  LSET  to  place 
what  is  actually  the  value  of  AMT  into  the  random 
file  buffer.  Line  120  places  a  string  into  the  buffer 
(we  don't  need  to  convert  a  string);  then  line  130 
writes  the  data  from  the  random  file  buffer  to  the 
file. 


100  FIELD     1 ,  ^  AS   D$ ,   20  AS  N $ 

1 1 0  LSET  D$  =  MKSS (AMTi 

12-5  LSET  N$  -  A$ 

13v3  PUT 


C/5 

> 

m 
Z 
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MOTOR 
Statement 


Purpose:     Turns  the  cassette  player  on  and  off  from  a  program. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  *** 


Format:      MOTOR  [state] 

Remarks:  state        is  a  numeric  expression  indicating  on  or 
off. 

If  state  is  non  zero,  the  cassette  motor  is  turned  on.  If 
state  is  zero,  the  cassette  motor  is  turned  off. 

If  state  is  omitted,  the  cassette  motor  state  is 
switched.  That  is,  if  the  motor  is  off,  it  is  turned  on 
and  vice-versa. 


Example:    The  following  sequence  of  statements  turns  the 
cassette  motor  on,  then  off,  then  back  on  again. 

10  MOTOR  1 
20  MOTOR  0 
30  MOTOR 
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NAME 
Command 


Purpose:     Changes  the  name  of  a  diskette  file.  The  NAME 
command  in  BASIC  is  similar  to  the  RENAME 
command  in  DOS. 


Versions:  Cassette 


Disk 


Advanced 
*** 


Compiler 


Format:      NAME  filespec  AS  filename 


Remarks:  filespec     is  a  file  specification  as  outlined  under 
"Naming  Files"  in  Chapter  3. 

filename    will  be  the  new  filename.  It  must  be  a  valid 
filename  as  outlined  in  the  same  section. 


The  file  specified  by  filespec  must  exist  and  filename 
must  not  exist  on  the  diskette,  otherwise  an  error 
will  result.  If  the  device  name  is  omitted,  the  DOS 
default  drive  is  assumed.  Note  that  the  file 
extension  does  not  default  to  .BAS. 

After  a  NAME  command,  the  file  exists  on  the  same 
diskette,  in  the  same  area  of  diskette  space,  with  the 
new  name. 


Example:    NAME  1  'A  :  ACCTS  .  BAS 1 1  AS  "LEDGER  .  BAS1 1 

In  this  example,  the  file  that  was  formerly  named 
ACCTS. BAS  on  the  diskette  in  drive  A  will  now  be 
named  LEDGER.BAS. 
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NEW 
Command 


Purpose:     Deletes  the  program  currently  in  memory  and  clears 
all  variables. 


Versions:  Cassette 
*** 


Disk 
*** 


Advanced 
*** 


Compiler 


Format:  NEW 


Remarks:    NEW  is  usually  used  to  free  memory  before 

entering  a  new  program.  BASIC  always  returns  to 
command  level  after  NEW  is  executed.  NEW  causes 
all  files  to  be  closed  and  turns  trace  off  if  it  was  on 
(see  "TRON  and  TROFF  Commands,"  later  in  this 
chapter). 


Example:  Ok 

N  EW 

Ok 


The  program  that  had  been  in  memory  is  now 
deleted. 
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OCT$ 
Function 


Purpose:     Returns  a  string  which  represents  the  octal  value  of 
the  decimal  argument. 


Versions:     Cassette     Disk      Advanced  Compiler 


Format:      v$  =  OCT$(«) 


Remarks:   n      is  a  numeric  expression  in  the  range  -32768  to 
65535. 

If  n  is  negative,  the  two's  complement  form  is  used. 
That  is,  OCT$(-/?)  is  the  same  as  OCT$(655  36-/?). 

See  the  HEX$  function  for  hexadecimal  conversion. 


Example:  Ok 

PRINT  0CT$(2M 

30 
Ok 

This  example  shows  that  24  in  decimal  is  30  in  octal. 
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ON  COM(n) 
Statement 


Purpose:     Sets  up  a  line  number  for  BASIC  to  trap  to  when 
there  is  information  coming  into  the 
communications  buffer. 


Versions:    Cassette      Disk      Advanced  Compiler 

***  (**) 


Format:     ON  COM(»)  GOSUB  line 


Remarks:   n  is  the  number  of  the  communications 

adapter  (1  or  2). 

line  is  the  line  number  of  the  beginning  of  the 

trap  routine.  Setting  line  equal  to  0  (zero) 
disables  trapping  of  communications 
activity  for  the  specified  adapter. 

A  COM(«)  ON  statement  must  be  executed  to 
activate  this  statement  for  adapter  n.  After  COM(#) 
ON,  if  a  non-zero  line  number  is  specified  in  the  ON 
COM(n)  statement  then  every  time  the  program 
starts  a  new  statement,  BASIC  checks  to  see  if  any 
characters  have  come  in  to  the  specified 
communications  adapter.  If  so,  BASIC  performs  a 
GOSUB  to  the  specified  line. 

If  COM(«)  OFF  is  executed,  no  trapping  takes  place 
for  the  adapter.  Even  if  communications  activity 
does  take  place,  the  event  is  not  remembered. 

If  a  COM(tf)  STOP  statement  is  executed,  no 
trapping  takes  place  for  the  adapter.  However,  any 
characters  being  received  are  remembered  so  an 
immediate  trap  takes  place  when  COM(«)  ON  is 
executed. 
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When  the  trap  occurs  an  automatic  COM(«)  STOP  is 
executed  so  recursive  traps  can  never  take  place. 


ON  COM(n) 
Statement 


The  RETURN  from  the  trap  routine  automatically 
does  a  COM(/z)  ON  unless  an  explicit  COM(ff)  OFF 
was  performed  inside  the  trap  routine. 

Event  trapping  does  not  take  place  when  BASIC  is 
not  executing  a  program.  When  an  error  trap 
(resulting  from  an  ON  ERROR  statement)  takes 
place  all  trapping  is  automatically  disabled 
(including  ERROR,  STRIG(n),  PEN,  COM(n),  and 
KEY(n)). 

Typically  the  communications  trap  routine  reads  an 
entire  message  from  the  communications  line 
before  returning  back.  It  is  not  recommended  that 
you  use  the  communications  trap  for  single 
character  messages  since  at  high  baud  rates  the 
overhead  of  trapping  and  reading  for  each  individual 
character  may  allow  the  interrupt  buffer  for 
communications  to  overflow. 

You  may  use  RETURN  line  if  you  want  to  go  back  to 
the  BASIC  program  at  a  fixed  line  number.  Use  of 
this  non-local  return  must  be  done  with  care, 
however,  since  any  other  GOSUBs,  WHILEs,  or 
FORs  that  were  active  at  the  time  of  the  trap  will 
remain  active. 


Example:   150  ON  COM  (  I )   GOSUB  500 
1 60  COM ( 1 )  ON 


500  REM   incoming  characters 


590  RETURN  300 

This  example  sets  up  a  trap  routine  for  the  first 
communications  adapter  at  line  500. 
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ON  ERROR 
Statement 


Purpose:     Enables  error  trapping  and  specifies  the  first  line  of 
the  error  handling  subroutine. 

Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  {**\ 


Format:      ON  ERROR  GOTO  line 


Remarks:   line  is  the  line  number  of  the  first  line  of  the 

error  trapping  routine.  If  the  line  number 
does  not  exist,  an  "Undefined  line 
number"  error  results. 

Once  error  trapping  has  been  enabled,  all  errors 
detected  {including  direct  mode  errors)  will  cause  a  jump 
to  the  specified  error  handling  subroutine. 

To  disable  error  trapping,  execute  an  ON  ERROR 
GOTO  0.  Subsequent  errors  will  print  an  error 
message  and  halt  execution.  An  ON  ERROR 
GOTO  0  statement  that  appears  in  an  error  trapping 
subroutine  causes  BASIC  to  stop  and  print  the  error 
message  for  the  error  that  caused  the  trap.  It  is 
recommended  that  all  error  trapping  subroutines 
execute  an  ON  ERROR  GOTO  0  if  an  error  is 
encountered  for  which  there  is  no  recovery  action. 

Note:    If  an  error  occurs  during  execution  of 
an  error  handling  subroutine,  the  BASIC  error 
message  is  printed  and  execution  terminates. 
Error  trapping  does  not  occur  within  the  error 
handling  subroutine. 
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ON  ERROR 
Statement 


You  use  the  RESUME  statement  to  exit  from  the 
error  trapping  routine.  Refer  to  "RESUME 
Statement"  in  this  chapter. 


Example:    10  ON  ERROR  GOTO  100 

20  L  P  R  I  N T   "This   goes    10   the  printer." 
30  END 

100    I  '■'  ERR-27  THEN   PRINT   MCheck  printer" 
:  RESUME 

This  example  shows  how  you  might  trap  a  common 
error  —  forgetting  to  put  paper  in  the  printer,  or 
forgetting  to  switch  it  on. 


C/5 

H 
> 

m 

tn 
Z 

C/3 
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ON...GOSUB  and  ON... GOTO 
Statements 


Purpose:     Branches  to  one  of  several  specified  line  numbers, 
depending  on  the  value  of  an  expression. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      ON  n  GOTO  line[,lme}.. 
ONn  GOSUB 


Remarks:   n  is  a  numeric  expression  which  is  rounded 

to  an  integer,  if  necessary.  It  must  be  in  the 
range  0  to  255,  an  "Illegal  function  call" 
error  occurs. 

line  is  the  line  number  of  a  line  you  wish  to 

branch  to. 

The  value  of  n  determines  which  line  number  in  the 
list  will  be  used  for  branching.  For  example,  if  the 
value  of  n  is  3,  the  third  line  number  in  the  list  will  be 
the  destination  of  the  branch. 

In  the  ON...GOSUB  statement,  each  line  number  in 
the  list  must  be  the  first  line  number  of  a  subroutine. 
That  is,  you  eventually  need  to  have  a  RETURN 
statement  to  bring  you  back  to  the  line  following 
the  ON...GOSUB. 

If  the  value  of  n  is  zero  or  greater  than  the  number  of 
items  in  the  list  (but  less  than  or  equal  to  25  5), 
BASIC  continues  with  the  next  executable 
statement. 
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ON...GOSUB  and  ON...GOTO 

Statements 


Example:   The  first  example  branches  to  line  150  if  L-l  equals 
1,  to  line  300  if  L-l  equals  2,  to  line  320  if  L-l  equals 
3,  and  to  line  390  if  L-l  equals  4.  If  L-l  is  equal  to  0 
(zero)  or  is  greater  than  4,  then  the  program  just 
goes  on  to  the  next  statement. 

100  ON  L-1   GOTO  150,300,320,390 

The  next  example  shows  how  to  use  an 
ON...GOSUB  statement. 

1200  ON  A  GOSUB   1 300 , 1  A 00 


1300  REM  start  of  subroutine  for  A= 1 


1390  RETURN 
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ON  KEY(n) 
Statement 


Purpose:     Sets  up  a  line  number  for  BASIC  to  trap  to  when  the 
specified  function  key  or  cursor  control  key  is 
pressed. 


Versions:    Cassette  Disk 


Advanced 
*** 


Compiler 
(**) 


Format:      ON  KEY(n)  GOSUB  line 


Remarks:   n      is  a  numeric  expression  in  the  range  1  to  14 
indicating  the  key  to  be  trapped,  as  follows: 

1-10  function  keys  Fl  to  F10 

1 1  Cursor  Up 

12  Cursor  Left 

13  Cursor  Right 

14  Cursor  Down 


line  is  the  line  number  of  the  beginning  of  the 

trapping  routine  for  the  specified  key.  Setting 
line  equal  to  0  disables  trapping  of  the  key. 

A  KEY(tf)  ON  statement  must  be  executed  to 
activate  this  statement.  After  KEY(#)  ON,  if  a 
non-zero  line  number  is  specified  in  the  ON  KEY(/?) 
statement  then  every  time  the  program  starts  a  new 
statement,  BASIC  checks  to  see  if  the  specified  key 
was  pressed.  If  so,  BASIC  performs  a  GOSUB  to  the 
specified  line. 

If  a  KEY(tf)  OFF  statement  is  executed,  no  trapping 
takes  place  for  the  specified  key.  Even  if  the  key  is 
pressed,  the  event  is  not  remembered. 
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Statement 


If  a  KEY(tf)  STOP  statement  is  executed,  no 
trapping  takes  place  for  the  specified  key.  However, 
if  the  key  is  pressed  the  event  is  remembered,  so  an 
immediate  trap  takes  place  when  KEY(/z)  ON  is 
executed. 

When  the  trap  occurs  an  automatic  KEY(^)  STOP  is 
executed  so  recursive  traps  can  never  take  place. 
The  RETURN  from  the  trap  routine  automatically 
does  a  KEY(n)  ON  unless  an  explicit  KEY(n)  OFF 
was  performed  inside  the  trap  routine. 

Event  trapping  does  not  take  place  when  BASIC  is 
not  executing  a  program.  When  an  error  trap 
(resulting  from  an  ON  ERROR  statement)  takes 
place  all  trapping  is  automatically  disabled 
(including  ERROR,  STRIG(n),  PEN,  COM(n),  and 
KEY(n)). 

Key  trapping  may  not  work  when  other  keys  are 
pressed  before  the  specified  key.  The  key  that 
caused  the  trap  cannot  be  tested  using  INPUT$  or 
INKEY$,  so  the  trap  routine  for  each  key  must  be 
different  if  a  different  function  is  desired. 

You  may  use  RETURN  line  if  you  want  to  go  back  to 
the  BASIC  program  at  a  fixed  line  number.  Use  of 
this  non-local  return  must  be  done  with  care, 
however,  since  any  other  GOSUBs,  WHILEs,  or 
FORs  that  were  active  at  the  time  of  the  trap  will 
remain  active. 

KEY(«)  ON  has  no  effect  on  whether  the  soft  key 
values  are  displayed  at  the  bottom  of  the  screen. 
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ON  KEY(n) 
Statement 

Example:   The  following  is  an  example  of  a  trap  routine  for 
function  key  5 . 

100  ON   KEY (5)    GOSUB  200 
1 10   KEY ( 5)  ON 


200  REM   function   key   5  pressed 


2 '30  RETURN  }k\ 
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ON  PEN 
Statement 


Purpose:     Sets  up  a  line  number  for  BASIC  to  transfer  control 
to  when  the  light  pen  is  activated. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      ON  PEN  GOSUB  line 


Remarks:   line  is  the  line  number  of  the  beginning  of  the 

trap  routine  for  the  light  pen.  Using  a  line 
number  of  0  disables  trapping  of  the  light 
pen. 

A  PEN  ON  statement  must  be  executed  to  activate 
this  statement.  After  PEN  ON,  if  a  non-zero  line 
number  is  specified  in  the  ON  PEN  statement,  then 
every  time  the  program  starts  a  new  statement 
BASIC  will  check  to  see  if  the  pen  was  activated.  If 
so,  BASIC  performs  a  GOSUB  line. 

If  PEN  OFF  is  executed,  no  trapping  takes  place. 
Even  if  the  light  pen  is  activated,  the  event  is  not 
remembered. 

If  a  PEN  STOP  statement  is  executed,  no  trapping 
takes  place,  but  pen  activity  is  remembered  so  that 
an  immediate  trap  takes  place  when  PEN  ON  is 
executed. 

When  the  trap  occurs,  an  automatic  PEN  STOP  is 
executed  so  recursive  traps  can  never  take  place. 
The  RETURN  from  the  trap  routine  automatically 
does  a  PEN  ON  unless  an  explicit  PEN  OFF  was 
performed  inside  the  trap  routine. 
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ON  PEN 
Statement 

Event  trapping  does  not  take  place  when  BASIC  is 
not  executing  a  program.  When  an  error  trap 
(resulting  from  an  ON  ERROR  statement)  takes 
place  all  trapping  is  automatically  disabled  (including 
ERROR,  STRIG(n),  PEN,  COM(n),  and  KEY(n)). 

PEN(O)  is  not  set  when  pen  activity  causes  a  trap. 

You  may  use  RETURN  line  if  you  want  to  go  back  to 
the  BASIC  program  at  a  fixed  line  number.  Use  of 
this  non-local  return  must  be  done  with  care, 
however,  since  any  other  GOSUBs,  WHILEs,  or 
FORs  that  were  active  at  the  time  of  the  trap  will 
remain  active. 

Note:  Do  not  attempt  any  cassette  I/O  while 
PEN  is  ON. 


Example:   This  example  sets  up  a  trap  routine  for  the  light  pen. 

10  OA   Pit,   GOSUB  CM 

■AA^    !;  ;  'A      ■.  ;n  ■  ■   .:  !  i  <\t'    r   ■  "\ 
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ON  STRIG(n) 
Statement 


Purpose:     Sets  up  a  line  number  for  BASIC  to  trap  to  when  one 
of  the  joystick  buttons  (triggers)  is  pressed. 


Versions:    Cassette      Disk       Advanced  Compiler 

*  *  *  ( *  * ) 


Format:      ON  STRIG(»)  GOSUB  line 

Remarks:   n  may  be  0,  2,  4,  or  6,  and  indicates  the  button 

to  be  trapped  as  follows: 

0  button  Al 

2  button  Bl 

4  button  A2 

6  button  B2 

line       is  the  line  number  of  the  trapping  routine.  If 
line  is  0,  trapping  of  the  joystick  button  is 
disabled. 

A  STRIG(tf)  ON  statement  must  be  executed  to 
activate  this  statement  for  button  n.  If  STRIG(tf) 
ON  is  executed  and  a  non-zero  line  number  is 
specified  in  the  ON  STRIG(ff)  statement,  then  every 
time  the  program  starts  a  new  statement  BASIC 
checks  to  see  if  the  specified  button  has  been 
pressed.  If  so,  BASIC  performs  a  GOSUB  to  the 
specified  line. 

If  STRIG(;?)  OFF  is  executed,  no  trapping  takes 
place  for  button/?.  Even  if  the  button  is  pressed,  the 
event  is  not  remembered. 

If  a  STRIG(tf)  STOP  statement  is  executed,  no 
trapping  takes  place  for  button  n,  but  the  button 
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ON  STRIG(n) 
Statement 


being  pressed  is  remembered  so  that  an  immediate 
trap  takes  place  when  STRIG(w)  ON  is  executed. 

When  the  trap  occurs,  an  automatic  STRIG(w) 
STOP  is  executed  so  recursive  traps  can  never  take 
place.  The  RETURN  from  the  trap  routine 
automatically  does  a  STRIG(«)  ON  unless  an 
explicit  STRIG(/?)  OFF  was  performed  inside  the 
trap  routine. 

Event  trapping  does  not  take  place  when  BASIC  is 
not  executing  a  program.  When  an  error  trap 
(resulting  from  an  ON  ERROR  statement)  takes 
place  all  trapping  is  automatically  disabled 
(including  ERROR,  STRIG(n),  PEN,  COM(n),  and 
KEY(n)). 

Using  STRIG(tf)  ON  will  activate  the  interrupt 
routine  that  checks  the  button  status  for  the 
specified  joystick  button.  Downstrokes  that  cause 
trapping  will  not  set  functions  STRIG(O), 
STRIG(2),  STRIG(4),  or  STRIG(6). 

You  may  use  RETURN  line  if  you  want  to  go  back  to 
the  BASIC  program  at  a  fixed  line  number.  Use  of 
this  non-local  return  must  be  done  with  care, 
however,  since  any  other  GOSUBs,  WHILEs,  or 
FORs  that  were  active  at  the  time  of  the  trap  will 
remain  active. 

Example:    This  is  an  example  of  a  trapping  routine  for  the 
button  on  the  first  joystick. 

100  ON  STRIGI0)    GOSUB  2000 
I  i0  iTR  I  G i 2)  ON 


2  000  R l  M  s  u brout  i  n e  for    1  s  I   b ut fu 
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RETURN 


OPEN 
Statement 


Purpose:     Allows  I/O  to  a  file  or  device. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format: 


First  form: 


OPEN filespec  [FOR  mode]  AS  \f\filenum  [LEN=recf\ 
Alternative  form: 

OPEN  mode2,  [#]  filenum,  filespec  [,recl\ 


OUTPUT  specifies  sequential  output 
mode, 

INPUT       specifies  sequential  input 
mode. 

APPEND    specifies  sequential  output 


Note  that  mode  must  be  a  string  constant, 
not  enclosed  in  quotation  marks.  If  mode  is 
omitted,  random  access  is  assumed. 


mode2       in  the  alternative  form,  is  a  string 

expression  whose  first  character  is  one  of 
the  following: 


0  specifies  sequential  output  mode. 

1  specifies  sequential  input  mode. 

R     specifies  random  input/output  mode. 


Remarks:  mode 


in  the  first  form,  is  one  of  the  following: 


mode  where  the  file  is 
positioned  to  the  end  of  data 
on  the  file  when  it  is  opened. 
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OPEN 
Statement 


For  both  formats: 


filenum     is  an  integer  expression  whose  value  is 

between  one  and  the  maximum  number  of 
files  allowed.  In  Cassette  BASIC,  the 
maximum  number  is  4.  In  Disk  and 
Advanced  BASIC,  the  default  maximum  is 
3,  but  this  can  be  changed  with  the  /F: 
option  on  the  BASIC  command. 


filespec     is  a  string  expression  for  the  file 

specification  as  explained  under  "Naming 
Files"  in  Chapter  3. 

reel  is  an  integer  expression  which,  if  included, 

sets  the  record  length  for  random  files.  It 
may  range  from  1  to  32767.  reel  is  not  valid 
for  sequential  files.  The  default  record 
length  is  128  bytes.  ra;/may  not  exceed  the 
value  set  by  the  /S:  option  on  the  BASIC 
command. 


OPEN  allocates  a  buffer  for  I/O  to  the  file  or  device 
and  determines  the  mode  of  access  that  will  be  used 
with  the  buffer. 


filenum  is  the  number  that  is  associated  with  the  file 
for  as  long  as  it  is  open  and  is  used  by  other  I/O 
statements  to  refer  to  the  file  or  device. 


An  OPEN  must  be  executed  before  any  I/O  may  be 
done  to  a  device  or  file  using  any  of  the  following 
statements,  or  any  statement  or  function  requiring  a 
file  number: 


PRINT  #  INPUT  # 

PRINT  #  USING  LINE  INPUT  # 

WRITE  #  GET 

INPUT$  PUT 
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OPEN 
Statement 


GET  and  PUT  are  valid  for  random  files  (or 
communications  files  —  see  next  section).  A  diskette 
file  may  be  either  random  or  sequential,  and  a 
printer  may  be  opened  in  either  random  or 
sequential  mode;  however,  all  other  devices  may  be 
opened  only  for  sequential  operations. 

BASIC  normally  adds  a  line  feed  after  each  carriage 
return  (CHR$(13))  sent  to  a  printer.  However,  if 
you  open  a  printer  (LPTl:,  LPT2:,  or  LPT3:)  as  a 
random  file  with  width  255,  this  line  feed  is 
suppressed. 

APPEND  is  valid  only  for  diskette  files.  The  file 
pointer  is  initially  set  to  the  end  of  the  file  and  the 
record  number  is  set  to  the  last  record  of  the  file. 
PRINT  #  or  WRITE  #  will  then  extend  the  file. 

Note:  At  any  one  time,  it  is  possible  to  have  a 
particular  file  open  under  more  than  one  file 
number.  This  allows  different  modes  to  be  used 
for  different  purposes.  Or,  for  program  clarity, 
you  may  use  different  file  numbers  for  different 
modes  of  access.  Each  file  number  has  a 
different  buffer,  so  you  should  use  care  if  you 
are  writing  using  one  file  number  and  reading 
using  another  file  number. 

However,  a  file  cannot  be  opened  for  sequential 
output  or  append  if  the  file  is  already  open. 

If  the  device  name  is  omitted  when  you  are  using 
Cassette  BASIC,  CASl:  is  assumed.  If  you  are  using 
Disk  or  Advanced  BASIC,  the  DOS  default  drive  is 
assumed. 

If  CASl :  is  specified  as  the  device  and  the  filename  is 
omitted,  then  the  next  data  file  on  the  cassette  is 
opened. 
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In  Cassette  BASIC,  a  maximum  of  four  files  may  be 
open  at  one  time  (cassette,  printer,  keyboard,  and 
screen).  Note  that  only  one  cassette  file  may  be 
open  at  a  time.  For  Disk  and  Advanced  BASIC  the 
default  maximum  is  three  files.  You  can  override 
this  value  by  using  the  /F:  option  on  the  BASIC 
command. 

If  a  file  opened  for  input  does  not  exist,  a  "File  not 
found"  error  occurs.  If  a  file  which  does  not  exist  is 
opened  for  output,  append,  or  random  access,  a  file 
is  created. 

Any  values  given  outside  the  ranges  indicated  will 
result  in  an  "Illegal  function  call"  error.  The  file  is 
not  opened. 

See  "Appendix  B.  BASIC  Diskette  Input  and 
Output"  for  a  complete  explanation  of  using 
diskette  files.  Refer  to  the  next  section,  "OPEN 
"COM...  Statement,"  for  information  on  opening 
communications  files. 


Example:     10  OPEN  "DATA"  FOR  OUTPUT  AS    '  I 
or 

10  OPEN  "0" .  '  1  ,"DATA" 

Either  of  these  statements  opens  the  file  named 
"DATA"  for  sequential  output  on  the  default  device 
(CASl:  for  Cassette  BASIC,  default  drive  for  Disk 
and  Advanced  BASIC).  Note  that  opening  for 
output  destroys  any  existing  data  in  the  file.  If  you 
do  not  wish  to  destroy  data  vou  should  open  for 
APPEND. 

20  OPEN  1 1 B  :  S S  M  L E 1    AS   1  LEN-256 
or 

20  OPEN  "R",  1  ,"B:SSFILE",256 
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Either  of  the  preceding  two  statements  opens  the 
file  named  "SSFILE"  on  the  diskette  in  drive  B  for 
random  input  and  output.  The  record  length  is  256. 

25  FILES  -  "A : DATA . ART1 1 

30  OPE  N  FILE  $  FOR  APPEND  AS  3 

This  example  opens  the  file  "DATA.ART"  on  the 
diskette  in  drive  A  and  positions  the  file  pointers  so 
that  any  output  to  the  file  is  placed  at  the  end  of 
existing  data  in  the  file. 

Ok 

10  OPEN  "LPT  1  :  1 1  AS      T    random  accov, 
20   PR  I  NT      1  ,  "Pri  n  I  i  nq  width   80' 1 
30   PRINT      1  ,"Nui,'  charier   to  widt  h  255' 
^0  W  I  DTH   ■■■  1  ,255 

50  PRINT    •  1  ,"This   1  ino  will   be  unclrrl  im-d" 

60  W I DTH   ■  1  , 80 

70  PRI  NT    •  1  ,    STRINGS  128  , 

80  PRINT  1  ,"Pr  i  nt  i  ncj  w  i  dTh  80  with  CR/LF" 
RUN 

P  r  i  n  L  i  nc]  w  i  d  I.  h  80 

No1.,  chnnoo   t  o  w  i  cJ  t  h  255 

Tliis    1  i  no  w  ill    be   nn  do  r  1  i  nod 

>"i  nTfn  <7  ~  >u~ih  80  \T\Tu~CR7Tf 

Ok 

Line  10  in  this  example  opens  the  printer  in  random 
mode.  Because  the  default  width  is  SO,  the  lines 
printed  by  lines  20  and  30  end  with  a  carriage 
return/line  feed.  Line  40  changes  the  printer  width 
to  25  5,  so  the  line  feed  after  the  carriage  return  is 
suppressed.  Therefore,  the  line  printed  by  line  50 
ends  only  with  a  carriage  return  and  not  a  line  feed. 
This  causes  the  line  printed  by  line  70  to  overprint 
"This  line  will  be  underlined",  causing  the  line  to  be 
underlined.  Line  60  changes  the  width  back  to  80  so 
the  underlines  and  following  lines  will  end  with  a 
line  feed. 
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OPEN  "COM... 
Statement 


Purpose:     Opens  a  communications  file. 


Versions:    Cassette     Disk      Advanced  Compiler 

***  ***  ^**^ 

Valid  only  with  Asynchronous  Communications 
Adapter. 


Format:      OPEN  "COMti\[speed\  [parity]  [,data]  [,stop] 
[,RS]  [,CS[»]]  [,DS[«]]  [,CD[«]]  [,LF]" 
AS  \jf\fihnum  [LEN=number] 


Remarks:   n  is  1  or  2,  indicating  the  number  of  the 

Asynchronous  Communications  Adapter. 

speed        is  an  integer  constant  specifying  the 

transmit/ receive  bit  rate  in  bits  per  second 
(bps).  Valid  speeds  are  75,  110,  150,  300, 
600,  1200,  1800,  2400, 4800,  and  9600. 
The  default  is  300  bps. 

parity       is  a  one-character  constant  specifying  the 
parity  for  transmit  and  receive  as  follows: 

S      SPACE:  Parity  bit  always  transmitted 
and  received  as  a  space  (0  bit). 

O     ODD:  Odd  transmit  parity,  odd 
receive  parity  checking. 

M     MARK:  Parity  bit  always  transmitted 
and  received  as  a  mark  (1  bit). 
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E      EVEN:  Even  transmit  parity,  even 
receive  parity  checking. 

N     NONE:  No  transmit  parity,  no 
receive  parity  checking. 

The  default  is  EVEN  (E). 

data         is  an  integer  constant  indicating  the 
number  of  transmit/receive  data  bits. 
Valid  values  are:  4,5,6,7,or8.  The  default 
is  7. 


stop  is  an  integer  constant  indicating  the 

number  of  stop  bits.  Valid  values  are  1  or 
2.  The  default  is  two  stop  bits  for  75  and 
110  bps,  one  stop  bit  for  all  others.  If  you 
use  4  or  5  for  data,  a  2  here  will  mean  1  1/2 
stop  bits. 

filenum     is  an  integer  expression  which  evaluates  to 
a  valid  file  number.  The  number  is  then 
associated  with  the  file  for  as  long  as  it  is 
open  and  is  used  by  other  communications 
I/O  statements  to  refer  to  the  file. 


number     is  the  maximum  number  of  bytes  which 
can  be  read  from  the  communication 
buffer  when  using  GET  or  PUT.  The 
default  is  128  bvtes. 


OPEN  "COM...  allocates  a  buffer  for  I/O  in  the 
same  fashion  as  OPEN  for  diskette  files.  It  supports 
RS232  asynchronous  communication  with  other 
computers  and  peripherals. 

A  communications  device  may  be  open  to  only  one 
file  number  at  a  time. 
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The  RS,  CS,  DS,  CD,  and  LF  options  affect  the  line 
signals  as  follows: 


RS 

suppresses  RTS  (Request  To  Send). 

CS[«] 

controls  CTS  (Clear  To  Send). 

DS[«] 

controls  DSR  (Data  Set  Ready). 

CD[n] 

controls  CD  (Carrier  Detect). 

LF 

sends  a  line  feed  following  each  carriage 

return. 

The  CD  (Carrier  Detect)  is  also  known  as  the  RLSD 
(Received  Line  Signal  Detect). 

Note:    The  speed,  parity,  data,  and  stop 
parameters  are  positional,  butRS,  CS,  DS,  CD, 
and  LF  are  not. 

The  RTS  (Request  To  Send)  line  is  turned  on  when 
you  execute  an  OPEN  "COM...  statement  unless 
you  include  the  RS  option. 

The  n  argument  in  the  CS,  DS,  and  CD  options 
specifies  the  number  of  milliseconds  to  wait  for  the 
signal  before  returning  a  "Device  Timeout"  error,  n 
may  range  fromO  to  65  5  35.  If  «  is  omitted  or  is  equal 
to  zero,  then  the  line  status  is  not  checked  at  all. 

The  defaults  are  CSlOOO,  DS1000,  and  CDO.  If  RS 

was  specified,  CSO  is  the  default. 

That  is,  normally  I/O  statements  to  a 
communications  file  will  fail  if  the  CTS  (Clear  To 
Send)  or  DSR  (Data  Set  Ready)  signals  are  off.  The 
system  waits  one  second  before  returning  a  "Device 
Timeout."  The  CS  and  DS  options  allow  you  to 
ignore  these  lines  or  to  specify  the  amount  of  time 
to  wait  before  the  timeout. 


4-196 


OPEN  "COM... 
Statement 


Normally  Carrier  Detect  (CD  or  RLSD)  is  ignored 
when  an  OPEN  "COM...  statement  is  executed.  The 
CD  option  allows  you  to  test  this  line  by  including 
the  n  parameter,  in  the  same  way  as  CS  and  DS.  If  n  is 
omitted  or  is  equal  to  zero,  then  Carrier  Detect  is 
not  checked  at  all  (which  is  the  same  as  omitting  the 
CD  option). 

The  LF  parameter  is  intended  for  those  using 
communication  files  as  a  means  of  printing  to  a  serial 
line  printer.  When  you  specify  LF,  a  line  feed 
character  (hex  OA)  is  automatically  sent  after  each 
carriage  return  character  (hex  OC).  (This  includes 
the  carriage  return  sent  as  a  result  of  the  width 
setting.)  Note  that  INPUT  #  and  LINE  INPUT  #, 
when  used  to  read  from  a  communications  file  that 
was  opened  with  the  LF  option,  stop  when  they  see  a 
carriage  return.  The  line  feed  is  always  ignored. 

Any  coding  errors  within  the  string  expression 
starting  with  speed  results  in  a  "Bad  file  name"  error. 
An  indication  as  to  which  parameter  is  in  error  is  not 
given. 

Refer  to  "Appendix  F.  Communications"  for  more 
information  on  control  of  output  signals  and  other 
technical  information  on  communications  support. 

If  you  specify  8  data  bits,  you  must  specify  parity  N. 
If  you  specify  4  data  bits,  you  must  specify  a  parity, 
that  is,  N  parity  is  invalid.  BASIC  uses  all  8  bits  in  a 
byte  to  store  numbers,  so  if  you  are  transmitting  or 
receiving  numeric  data  (for  example,  by  using  PUT), 
you  must  specify  8  data  bits.  (This  is  not  the  case  if 
you  are  sending  numeric  data  as  text.) 

Refer  to  the  previous  section  for  opening  devices 
other  than  communications  devices. 
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OPEN  "COM... 
Statement 


Example:    }'/  QP[  N  ■ -(.or, !  : ' !  AS  I 

File  1  is  opened  for  communication  with  all  defaults. 
The  speed  is  300  bps  with  even  parity.  There  will  be 
7  data  bits  and  one  stop  bit. 

U*  op;  n    cu-\  as  : 

File  2  is  opened  for  communication  at  2400  bps. 
Parity,  number  of  data  bits,  and  number  of  stop  bits 
are  defaulted. 

File  number  1  is  opened  for  asynchronous  I/O  at 
1200  bps,  no  parity  is  to  be  produced  or  checked, 
8-bit  bytes  will  be  sent  and  received,  and  1  stop  bit 
will  be  transmitted. 

■  ■/>  or?  ;„  •  AO'-1 1  :  o00  .  '1 ,  8 ,  ,  -  s ,  us  ,  (  \v    -s  ; 

Opens  COMl:  at  9600  bps  with  no  parity  and  eight 
data  bits.  CTS,  DSR,  and  RLSD  are  not  checked. 

'■0  UPLii  "oUM  i  :  ;  ?00  .  ,  ,  ,  I  S  .  U S 2 0 0 0 1 ;  AS  \ 

Opens  COMl:  at  1200  bps  with  the  defaults  of  even 
parity  and  seven  data  bits.  RTS  is  sent,  CTS  is  not 
checked,  and  "Device  Timeout"  is  given  if  DSR  is 
not  seen  within  two  seconds.  Note  that  the  commas 
are  required  to  indicate  the  position  of  the  parity, 
start,  And  stop  parameters,  even  though  a  value  is  not 
specified.  This  is  what  is  meant  by  positional 
parameters. 
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OPEN  "COM... 
Statement 


An  OPEN  statement  may  be  used  with  an  ON 
ERROR  statement  to  make  sure  a  modem  is 
working  properly  before  sending  any  data.  For 
example,  the  following  program  makes  sure  we  get 
Carrier  Detect  (CD  or  RLSD)  from  the  modem 
before  starting.  Line  20  is  set  to  timeout  after  10 
seconds.  TRIES  is  set  to  6  so  we  give  up  if  Carrier 
Detect  is  not  seen  within  one  minute.  Once 
communication  is  established,  we  re-open  the  file 
with  a  shorter  delay  until  timeout. 

i>  TR  It  S--6 

10  ON  ERROR  GOTO  100 

20  OPE  N    :C0M1  :  300 . N , 8 , 2 , CS , DS , CD  10000' 1  AS  i 

30  ON   ERROR  ROTO  0 

00   CLOSE      1    '    './url.  ■    S'  ■  cnn  con!  i  nu..- 
•>0  SCO  1000 


100  TR  I  E S ------ T  R  1  E.S-  1 

110  I!  TRiES-0  THE N  ON  ERROR  GOTO  0 
1  20  R!  SOME 


1000   OPEN  "COM!  :  300  ,  N  ,S,  2  .05  ,  DS  ,  CR20001'  AS 

The  next  example  shows  a  typical  way  to  use  a 
communication  file  to  control  a  serial  line  printer. 
The  LF  parameter  in  the  OPEN  statement  ensures 
that  lines  do  not  print  on  top  of  each  other. 

10  Wl  2)TH  "COR!  : 1  A    1  32 

20  OPEN  -'COMI  :  i  200  ,  N  ,  8  ,  ,  CS  1  0000  .  DS  10000  , 

OR  10000  ,IT"  AS   -  1 
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OPTION  BASE 
Statement 


Purpose:     Declares  the  minimum  value  for  array  subscripts. 

Versions:    Cassette      Disk      Advanced  Compiler 
*  *  *  ***  **  *  *  *  * 

Format:      OPTION  BASE  n 

Remarks:   n  is  1  or  0, 

The  default  base  is  0.  If  the  statement: 

OPTION  BASE  i 

is  executed,  the  lowest  value  an  array  subscript  may 
have  is  one. 

The  OPTION  BASE  statement  must  be  coded  before 
you  define  or  use  any  arrays. 
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OUT 
Statement 


Purpose:     Sends  a  byte  to  a  machine  output  port. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      OUT  n,m 


Remarks:   n      is  a  numeric  expression  for  the  port  number,  in 
the  range  0-65  5  35. 

m     is  a  numeric  expression  for  the  data  to  be 
transmitted,  in  the  range  0-255. 

Refer  to  the  IBM  Personal  Computer  Technical  Reference 
manual  for  a  description  of  valid  port  numbers  (I/O 
addresses). 

OUT  is  the  complementary  statement  to  the  INP 
function.  Refer  to  "INP  Function"  in  this  chapter. 

One  use  of  OUT  is  to  affect  the  video  output.  On 
some  displays  attached  to  the  Color/Graphics 
Monitor  Adapter,  you  may  find  that  the  first  two  or 
three  characters  on  the  line  don't  show  up  on  the 
screen.  If  your  display  does  not  have  a  horizontal 
adjustment  control,  you  can  use  the  following 
statements  to  shift  the  display: 

OUT   980  ,2:    OUT  9 8 1  ,^3 

This  shifts  the  display  two  characters  to  the  right  in 
40-column  width  (or  16  points  in  medium 
resolution  graphics  mode,  or  32  points  in  high 
resolution  graphics  mode). 
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OUT 

Statement 


OUT  380,2:    OUT  98 1 ,85 

This  shifts  the  display  right  five  characters  in 
80-column  width. 

The  shift  caused  by  these  OUT  statements  remains 
in  effect  until  a  WIDTH  or  SCREEN  statement  is 
executed.  The  MODE  command  from  DOS  can  also 
be  used  to  shift  the  display  as  described  here;  it  has 
the  benefit  of  remaining  in  effect  until  a  System 
Reset. 


Example:    130  OUT  3? ,  100 

This  sends  the  value  100  to  output  port  32. 


4-202 


PAINT 
Statement 


Purpose:     Fills  in  an  area  on  the  screen  with  the  selected  color. 


Versions:    Cassette      Disk      Advanced  Compiler 


Graphics  mode  only. 


Format:      PAINT  (xry)  [,paint  [^boundary]} 


Remarks:  (x,y) 


paint 


are  the  coordinates  of  a  point  within  the 
area  to  be  filled  in.  The  coordinates  may  be 
given  in  absolute  or  relative  form  (see 
"Specifying  Coordinates"  under 
"Graphics  Modes"  in  Chapter  3).  This 
point  will  be  used  as  a  starting  point. 

is  the  color  to  be  painted  with,  in  the  range 
0  to  3-  In  medium  resolution,  this  color  is 
the  color  from  the  current  palette  as 
defined  by  the  COLOR  statement.  0  is  the 
background  color.  The  default  is  the 
foreground  color,  color  number  3.  In  high 
resolution, paint  equal  to  0  (zero)  indicates 
black,  and  the  default  of  1  (one)  indicates 
white. 


boundary  is  the  color  of  the  edges  of  the  figure  to  be 
filled  in,  in  the  range  0  to  3  as  described 
above. 


The  figure  to  be  filled  in  is  the  figure  with  edges  of 
boundary  color.  The  figure  is  filled  in  with  the  color 
paint. 
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PAINT 
Statement 


Since  there  are  only  two  colors  in  high  resolution  it 
doesn't  make  sense  for  paint  to  be  different  from 
boundary.  Since  boundary  is  defaulted  to  equ.&\ paint  we 
don't  need  the  third  parameter  in  high  resolution 
mode. 

In  high  resolution  this  means  "blacking  out"  an  area 
until  black  is  hit,  or  "whiting  out"  an  area  until 
white  is  hit. 

In  medium  resolution  we  can  fill  in  with  color  1  with 
a  border  of  color  2.  Visually  this  might  mean  a  green 
ball  with  a  red  border. 

The  starting  point  of  PAINT  must  be  inside  the 
figure  to  be  painted.  If  the  specified  point  already 
has  the  color  boundary  then  PAINT  will  have  no 
effect.  If  paint  is  omitted  the  foreground  color  is 
used  (3  in  medium  resolution,  1  in  high  resolution). 
PAINT  can  paint  any  type  of  figure,  but  "jagged" 
edges  on  a  figure  will  increase  the  amount  of  stack 
space  required  by  PAINT.  So  if  a  lot  of  complex 
painting  is  being  done  you  may  want  to  use  CLEAR 
at  the  beginning  of  the  program  to  increase  the 
stack  space  available. 

The  PAINT  statement  allows  scenes  to  be  displayed 
with  very  few  statements.  This  can  be  a  very  useful 
capability. 

Example:   5  SCREEN  1 

10  LINE   (0,0) -  000,  150)  ,2,B 
20  PAINT   (50,50) , 1  ,2 

The  PAINT  statement  in  line  20  fills  in  the  box 
drawn  in  line  10  with  color  1. 
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PEEK 
Function 


Purpose:     Returns  the  byte  read  from  the  indicated  memory 
position. 

Versions:    Cassette      Disk      Advanced  Compiler 


Format:      v  =  PEEK(tf) 


Remarks:   n      is  an  integer  in  the  range  0  to  65  5  35.  n  is  the 
offset  from  the  current  segment  as  defined  by 
the  DEF  SEG  statement,  and  indicates  the 
address  of  the  memory  location  to  be  read.  (See 
"DEF  SEG  Statement"  in  this  chapter.) 

The  returned  value  will  be  an  integer  in  the  range  0 
to  255. 

PEEK  is  the  complementary  function  to  the  POKE 
statement  (see  "POKE  Statement,"  later  in  this 
chapter). 

Example:   The  following  example  can  be  used  in  a  program  to 
test  which  display  adapter  is  on  the  system.  After 
line  30  is  executed,  the  variable  IBMMONO  will 
have  a  value  of  0  (zero)  if  the  Color/Graphics 
Monitor  Adapter  is  used,  or  1  (one)  if  the  IBM 
Monochrome  Display  and  Parallel  Printer  Adapter 
is  used. 


10    'lest  display  adapter 
20  DEF  SEG=0 

30   I F   (PEEK(&410)   AND  &H30) 
THEN  IBMM0N0-1 
ELSE  IBMMONO=0 


=  &H30 
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PEN 

Statement  and  Function 


Purpose:     Reads  the  light  pen. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  (**) 

PEN  STOP  only  in  Advanced  and  Compiler. 


Format:      As  a  statement: 
PEN  ON 
PEN  OFF 
PEN  STOP 
As  a  function: 
v  =  PEN(/?) 

Remarks:    The  PEN  function,  y=PEN(»),  reads  the  light  pen 
coordinates. 

n      is  a  numeric  expression  in  the  range  0  to  9,  and 
affects  the  value  returned  by  the  function  as 
follows: 


0  A  flag  indicating  if  pen  was  down  since  last 
poll.  Returns  -1  if  down,  0  if  not. 

1  Returns  the  x  coordinate  where  pen  was 
last  activated.  Range  is  0  to  319  in  medium 
resolution,  or  0  to  639  in  high  resolution. 

2  Returns  the  y  coordinate  where  pen  was 
last  activated.  Range  is  0  to  199- 

3  Returns  the  current  pen  switch  value.  -1  if 
down,  0  if  up. 
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PEN 

Statement  and  Function 

4  Returns  the  last  known  valid  x  coordinate. 
Range  is  0  to  3 19  in  medium  resolution,  or 
0  to  639  in  high  resolution. 

5  Returns  the  last  known  valid  y  coordinate. 
Range  is  0  to  199. 

6  Returns  the  character  row  position  where 
pen  was  last  activated.  Range  is  1  to  24. 

7  Returns  the  character  column  position 
where  pen  was  last  activated.  Range  is  1  to 
40  or  1  to  80  depending  on  WIDTH. 

8  Returns  the  last  known  valid  character 
row.  Range  is  1  to  24. 


9      Returns  the  last  known  valid  character 
column  position.  Range  is  1  to  40  or  1  to 
80  depending  on  WIDTH. 

PEN  ON  enables  the  PEN  read  function.  The  PEN 
function  is  initially  off.  A  PEN  ON  statement  must 
be  executed  before  any  pen  read  function  calls  can 
be  made.  A  call  to  the  PEN  function  while  the  PEN 
function  is  off  results  in  an  "Illegal  function  call" 
error. 


Conversely,  for  execution  speed  improvements,  it  is 
a  good  idea  to  turn  the  pen  off  with  a  PEN  OFF 
statement  when  you  are  not  using  the  light  pen. 


For  Advanced  BASIC,  executing  PEN  ON  will  also 
allow  trapping  to  take  place  with  the  ON  PEN 
statement.  After  PEN  ON,  if  a  nonzero  line  number 
was  specified  in  the  ON  PEN  statement,  then  every 
time  the  program  starts  a  new  statement  BASIC 
checks  to  see  if  the  pen  was  activated.  Refer  to  "ON 
PEN  Statement"  in  this  chapter. 
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PEN 

Statement  and  Function 


PEN  OFF  disables  the  PEN  read  function.  For 
Advanced  BASIC,  no  trapping  of  the  pen  takes  place 
and  action  by  the  light  pen  is  not  remembered  even 
if  it  does  take  place. 

PEN  STOP  is  only  available  in  Advanced  BASIC.  It 
disables  trapping  of  light  pen  activity,  but  if  activity 
happens  it  is  remembered  so  an  immediate  trap 
occurs  when  a  PEN  ON  is  executed. 

When  the  pen  is  down  in  the  border  area  of  the 
screen,  the  values  returned  are  inaccurate. 

You  should  not  attempt  I/O  to  cassette  while  PEN  is 
ON. 


Example:    50  PEN  ON 

60  FOR   1=1   TO  500 

70  X=PEN (0) :   X1=PEN (3) 

30  PRINT  X,  XI 

90  NEXT 

100  PEN  OFF 

This  example  prints  the  pen  value  since  the  last  poll, 
and  the  current  value. 
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PLAY 
Statement 


Purpose:     Plays  music  as  specified  by  string. 


Versions:    Cassette      Disk      Advanced  Compiler 

***  (**) 


Format:      PLAY  string 


Remarks:    PLAY  implements  a  concept  similar  to  DRAW  by 
imbedding  a  "tune  definition  language"  into  a 
character  string. 

string       is  a  string  expression  consisting  of  single 
character  music  commands. 

The  single  character  commands  in  PLAY  are: 

A  to  G  with  optional  #,  +,  or  - 

Plays  the  indicated  note  in  the  current 
octave.  A  number  sign  (#)  or  plus  sign  {+) 
afterwards  indicates  a  sharp,  a  minus  sign  (-) 
indicates  a  flat.  The  #,  +,  or  -  is  not  allowed 
unless  it  corresponds  to  a  black  key  on  a 
piano.  For  example,  B#  is  an  invalid  note. 

O  n     Octave.  Sets  the  current  octave  for  the 
following  notes.  There  are  7  octaves, 
numbered  0  to  6.  Each  octave  goes  from  C  to 
B.  Octave  3  starts  with  middle  C.  Octave  4  is 
the  default  octave. 


N  n     Plays  note  n.  n  may  range  from  0  to  84.  In  the 
7  possible  octaves,  there  are  84  notes.  n=0 
means  rest.  This  is  an  alternative  way  of 
selecting  notes  besides  specifying  the  octave 
(O  n)  and  the  note  name  (A-G). 
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PJci&XllCIlC 


L  n      Sets  the  length  of  the  following  notes.  The 
actual  note  length  is  1/n.  n  may  range  from  1 
to  64.  The  following  table  may  help  explain 
this: 


Length 

Equivalent 

LI 

whole  note 

L2 

half  note 

L3 

one  of  a  triplet  of  three  half  notes 

(1/3  of  a  4  beat  measure) 

L4 

quarter  note 

L5 

one  of  a  quintuplet  (1/5  of  a 

measure) 

L6 

one  of  a  quarter  note  triplet 

L64         sixty- fourth  note 

The  length  may  also  follow  the  note  when 
you  want  to  change  the  length  only  for  the 
note.  For  example,  Al6  is  equivalent  to 
L16A. 

P  n      Pause  (rest),  n  may  range  from  1  to  64,  and 
figures  the  length  of  the  pause  in  the  same 
way  as  L  (length). 

(dot  or  period)  After  a  note,  causes  the  note 
to  be  played  as  a  dotted  note.  That  is,  its 
length  is  muhiphed  by^/2 .  ^  ^  R£ » 

default  is  120.  Under  "SOUND  Statement," 
later  in  this  chapter,  is  a  table  listing  common 
4-210  tempos  and  the  equivalent  beats  per  minute. 


PLAY 
Statement 


MF      Music  foreground.  Music  (created  by 

SOUND  or  PLAY)  runs  in  foreground.  That 
is,  each  subsequent  note  or  sound  will  not 
start  until  the  previous  note  or  sound  is 
finished.  You  can  press  Ctrl-Break  to  exit 
PLAY.  Music  foreground  is  the  default  state. 

MB      Music  background.  Music  (created  by 
SOUND  or  PLAY)  runs  in  background 
instead  of  in  foreground.  That  is,  each  note 
or  sound  is  placed  in  a  buffer  allowing  the 
BASIC  program  to  continue  executing  while 
music  plays  in  the  background.  Up  to  32 
notes  (or  rests)  may  be  played  in  background 
at  a  time. 


MN     Music  normal.  Each  note  plays  7/8  of  the 
time  specified  by  L  (length).  This  is  the 
default  setting  of  MN,  ML,  and  MS. 

ML      Music  legato.  Each  note  plays  the  full  period 
set  by  L  (length). 

MS      Music  staccato.  Each  note  plays  3/4  of  the 
time  specified  by  L. 

X  variable; 

Executes  specified  string. 


In  all  of  these  commands  the  n  argument  can  be  a 
constant  like  12  or  it  can  be  —variable;  where 
variable  is  the  name  of  a  variable.  The  semicolon  (;)  is 
required  when  you  use  a  variable  in  this  way,  and 
when  you  use  the  X  command.  Otherwise  a 
semicolon  is  optional  between  commands,  except  a 
semicolon  is  not  allowed  after  MF,  MB,  MN,  ML,  or 
MS.  Also,  any  blanks  in  string  are  ignored. 
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PLAY 
Statement 


You  can  also  specify  variables  in  the  form 
VARPTR$(variable),  instead  of  ^variable;.  This  is 
useful  in  programs  that  will  later  be  compiled.  For 
example: 

One  Method        Alternative  Method 

PLAY  "XAS;M  PLAY  "X 1 '+V  ARPTR  $  (A;) 

P LAY   '  '0--=  I  ;  "  P  LAY  '  '0= ' '+ VARPTR $  f  1  .) 

You  can  use  X  to  store  a  "subtune"  in  one  string  and 
call  it  repetitively  with  different  tempos  or  octaves 
from  another  string. 

Example:   The  following  example  plays  a  tune. 

10  REM   little  lamb 

20  MARY$="GFE-FGGG" 

30  PLAY  1  'MB  T100  03  L8;XMARY$;P3  FFFV 

40  PLAY  "GB-B-4:   XMAR Y  $  ;   GFFGFE  -  .  " 
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POINT 
Function 


Purpose:     Returns  the  color  of  the  specified  point  on  the 
screen. 


Versions:    Cassette      Disk      Advanced  Compiler 
**  *  *  *  *  *  *  *  *  *  * 


Graphics  mode  only. 


Format:      v  =  POINT  (x,y) 


Remarks:  {x,y) 


are  the  coordinates  of  the  point  to  be  used. 
The  coordinates  must  be  in  absolute  form 
(see  "Specifying  Coordinates"  under 
"Graphics  Modes"  in  Chapter  3). 


If  the  point  given  is  out  of  range  the  value  -1  is 
returned.  In  medium  resolution  valid  returns  are  0, 
1,  2,  and  3.  In  high  resolution  they  are  0  and  1, 


Example:   The  following  example  inverts  the  current  state  of 
point  (1,1). 


5  SCREEN  2 

10    If   P 0  I  NT ( I  , 


THEN  PRESET 
ELSE  PSET( I 


or 

PSET 


, I-POI NT 
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POKE 
Statement 


Purpose:     Writes  a  byte  into  a  memory  location. 


Versions:    Cassette      Disk      Advanced  Compiler 
***  #**  ***  *** 


Format:      POKE  n,m 


Remarks:   n      must  be  in  the  range  0  to  655  35  and  indicates 
the  address  of  the  memory  location  where  the 
data  is  to  be  written.  It  is  an  offset  from  the 
current  segment  as  defined  by  the  DEF  SEG 
statement  (see  "DEF  SEG  Statement"  in  this 
chapter). 

m     m  is  the  data  to  be  written  to  the  specified 
location.  It  must  be  in  the  range  0  to  255. 

The  complementary  function  to  POKE  is  PEEK. 
(See  "PEEK  Function"  in  this  chapter.)  POKE  and 
PEEK  are  useful  for  efficient  data  storage,  loading 
machine  language  subroutines,  and  passing 
arguments  and  results  to  and  from  machine 
language  subroutines. 

Warning: 

BASIC  does  not  do  any  checking  on  the  address. 
So  don't  go  POKEing  around  in  BASIC'S  stack, 
BASIC'S  variable  area,  or  your  BASIC  program. 


Example: 


See  "INKEY$  Variable"  in  this  chapter  for  an 
explanation  of  this  example. 
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POS 
Function 


Purpose:     Returns  the  current  cursor  column  position. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:     v  =  POS(») 


Remarks:   n      is  a  dummy  argument. 

The  current  horizontal  (column)  position  of  the 
cursor  is  returned.  The  returned  value  will  be  in  the 
range  1  to  40  or  1  to  80,  depending  on  the  current 
WIDTH  setting.  CSRLIN  can  be  used  to  find  the 
vertical  (row)  position  of  the  cursor  (see  "CSRLIN 
Variable"  in  this  chapter). 

Also  see  the  LPOS  function. 


Example: 


This  example  prints  a  carriage  return  (moves  the 
cursor  to  the  beginning  of  the  next  line)  if  the  cursor 
is  beyond  position  60  on  the  screen. 
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PRINT 
Statement 


Purpose:     Displays  data  on  the  screen. 

Versions:    Cassette      Disk      Advanced  Compiler 
*#*  ***  ***  *** 

Format:      PRINT  [list  of  expressions]  [;] 
?  [list  of  expressions]  [;] 


Remarks:   list  of  expressions 

is  a  list  of  numeric  and/or  string 
expressions,  separated  by  commas,  blanks, 
or  semicolons.  Any  string  constants  in  the 
list  must  be  enclosed  in  quotation  marks. 

If  the  list  of  expressions  is  omitted,  a  blank  line  is 
displayed.  If  the  list  of  expressions  is  included,  the 
values  of  the  expressions  are  displayed  on  the  screen. 

Note:    The  question  mark  (?)  may  be  used  as  a 
shorthand  way  of  entering  PRINT  only  when 
you  are  using  the  BASIC  program  editor. 


Print  Positions 

The  position  of  each  printed  item  is  determined  by 
the  punctuation  used  to  separate  the  items  in  the 
list.  BASIC  divides  the  line  into  print  zones  of  14 
spaces  each.  In  the  list  of  expressions,  a  comma 
causes  the  next  value  to  be  printed  at  the  beginning 
of  the  next  zone.  A  semicolon  causes  the  next  value 
to  be  printed  immediately  after  the  last  value. 
Typing  one  or  more  spaces  between  expressions  has 
the  same  effect  as  typing  a  semicolon. 
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PRINT 
Statement 


If  a  comma,  semicolon,  or  SPC  or  TAB  function 
ends  the  list  of  expressions,  the  next  PRINT 
statement  begins  printing  on  the  same  line,  spacing 
accordingly.  If  the  list  of  expressions  ends  without  a 
comma,  semicolon,  SPC  or  TAB  function,  a  carriage 
return  is  printed  at  the  end  of  the  line;  that  is,  BASIC 
moves  the  cursor  to  the  beginning  of  the  next  line. 


If  the  length  of  the  value  to  be  printed  exceeds  the 
number  of  character  positions  remaining  on  the 
current  line,  then  the  value  will  be  printed  at  the 
beginning  of  the  next  line.  If  the  value  to  be  printed 
is  longer  than  the  defined  WIDTH,  BASIC  prints  as 
much  as  it  can  on  the  current  line  and  continues 
printing  the  rest  of  the  value  on  the  next  physical 
line. 


Scrolling  occurs  as  described  under  "Text  Mode"  in 
Chapter  3. 

Printed  numbers  are  always  followed  by  a  space. 
Positive  numbers  are  preceded  by  a  space.  Negative 
numbers  are  preceded  by  a  minus  sign. 
Single-precision  numbers  that  can  be  represented 
with  7  or  fewer  digits  in  fixed  point  format  no  less 
accurately  than  they  can  be  represented  in  the 
floating  point  format,  are  output  using  fixed  point 
or  integer  format.  For  example,  10"  (-7)  is  output  as 
.0000001  and  10"  (-8)  is  output  as  1E-8. 


BASIC  automatically  inserts  a  carriage  return/line 
feed  after  printing  width  characters,  where  width  is  40 
or  80,  as  defined  by  the  WIDTH  statement.  This  will 
cause  two  lines  to  be  skipped  when  you  print  exactly 
40  (or  80)  characters,  unless  the  PRINT  statement 
ends  in  a  semicolon  (;). 

LPRINT  is  used  to  print  information  on  the  printer. 
See  "LPRINT  and  LPRINT  USING  Statements" 
earlier  in  this  chapter. 
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PRINT 
Statement 


Example:  Ok 

10  X=5 

20  PRINT  X  +  5,  X-5,  X--'(-5) 
30  END 

RUN 

10  0  -25 

Ok 

In  this  example,  the  commas  in  the  PRINT 
statement  cause  each  value  to  be  printed  at  the 
beginning  of  the  next  print  zone. 

Ok 

10    INPUT  X 

20  PRINT   X  "SQUARED   IS"  X~2  "AND"; 

30  PRINT   X  "CUBED    IS"  X~ 3 

RUN 

;  'j 

9  SQUARED   IS  81  AND  9  CUBED   IS  729 
Qk 
RUN 

:  2 1 

2:    SQUARED    IS   V(1    AND  2  1    CUBED   IS  92  6 1 
Ok 

Here,  the  semicolon  at  the  end  of  line  20  causes  both 
PRINT  statements  to  be  printed  on  the  same  line. 

Ok 

10  FOR  X  -   1   TO  5 

20  j=J+5 

30  ;<=k-M0 

T0  ?  J  ;  :< ; 

30  NEXT  k 

RUN 

5     10      0     20     15     30     20     ^0     2  5  50 
01- 

Here,  the  semicolons  in  the  PRINT  statement  cause 
each  value  to  be  printed  immediately  after  the 
preceding  value.  (Don't  forget,  a  number  is  always 
followed  by  a  space  and  positive  numbers  are 
preceded  by  a  space.)  In  line  40,  a  question  mark  is 
/  used  instead  of  the  word  PRINT. 


PRINT  USING 
Statement 


Purpose:  Prints  strings  or  numbers  using  a  specified  format. 
Versions:    Cassette      Disk      Advanced  Compiler 

Format:      PRINT  USING  v$;  list  of  expressions  [;] 


Remarks:  v$  is  a  string  constant  or  variable  which  consists  of 
special  formatting  characters.  These  formatting 
characters  (see  below)  determine  the  field  and 
the  format  of  the  printed  strings  or  numbers. 

list  of  expressions 

consists  of  the  string  expressions  or  numeric 
expressions  that  are  to  be  printed,  separated  by 
semicolons  or  commas. 


String  Fields 

When  PRINT  USING  is  used  to  print  strings,  one  of 
three  formatting  characters  may  be  used  to  format 
the  string  field: 

!  Specifies  that  only  the  first  character  in 

the  given  string  is  to  be  printed. 

\n  spaces\    Specifies  that  2+n  characters  from  the 
string  are  to  be  printed.  If  the 
backslashes  are  typed  with  no  spaces, 
two  characters  are  printed;  with  one 
space,  three  characters  are  printed,  and 
so  on. 
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PRINT  USING 
Statement 


If  the  string  is  longer  than  the  field,  the 
extra  characters  are  ignored.  If  the  field  is 
longer  than  the  string,  the  string  is 
left-justified  in  the  field  and  padded  with 
spaces  on  the  right. 

Example: 

10  A$="L00K":  BS-"0UT" 

30  PR.  I  NT  US  !  ,NG  ,;  !  1  A  AS  ;  B3 

^0  PR  I  NT  US  I  NG  : '         11  ;A5  ;  BS 

50  PRINT  US  I  NG  ,!  ";A$;B$;"!  !' 

RUN 

LO 

LOOKOUT 
LOOK  OUT     ! ! 

&  Specifies  a  variable  length  string  field. 

When  the  field  is  specified  with  "&",  the 
string  is  output  exactly  as  input.  Example: 

10  A$:="L00K":   BS  =  "0UT" 
20  PRINT  USING  !,!";AS; 
30  PR  I  NT  USING  'UU';BS 
RUN 
LOUT 


Numeric  Fields 

When  PRINT  USING  is  used  to  print  numbers,  the 
following  special  characters  may  be  used  to  format 
the  numeric  field: 

#  A  number  sign  is  used  to  represent  each 

digit  position.  Digit  positions  are  always 
filled.  If  the  number  to  be  printed  has 
fewer  digits  than  positions  specified,  the 
number  is  right-justified  (preceded  by 
spaces)  in  the  field. 
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PRINT  USING 
Statement 


A  decimal  point  may  be  inserted  at  any 
position  in  the  field.  If  the  format  string 
specifies  that  a  digit  is  to  precede  the 
decimal  point,  the  digit  will  always  be 
printed  (as  0  if  necessary).  Numbers  are 
rounded  as  necessary. 

PRINT  US  !  NG         .  .  78 


PRINT  USING  1 J .  ---  1 1  ;  9  8  7  -  6  5  ^ 
987-65 

PRINT  USING  ";  10.2,5.3,66.789,  .2  3h 

10.20         5.30  66.79  0.23 

In  the  last  example,  three  spaces  were 
inserted  at  the  end  of  the  format  string  to 
separate  the  printed  values  on  the  line. 

+  A  plus  sign  at  the  beginning  or  end  of  the 

format  string  causes  the  sign  of  the 
number  (plus  or  minus)  to  be  printed 
before  or  after  the  number. 

-  A  minus  sign  at  the  end  of  the  format  field 

causes  negative  numbers  to  be  printed 
with  a  trailing  minus  sign. 

PRINT  USING  '''  +  ..■  ■•' . "  ; -68.  95  ,2  .  k  ,55- 6,  -  . c; 
-68.95        +  2.^0      +55-60  -0.90 

PRINT  USING  M;-68. 95, 22.^^9, -7-01 

68.95-       22.^5  7-01- 

**  A  double  asterisk  at  the  beginning  of  the 

format  string  causes  leading  spaces  in  the 
numeric  field  to  be  filled  with  asterisks. 
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PRINT  USING 
Statement 


The  **  also  specifies  positions  for  two 
more  digits. 


$$  A  double  dollar  sign  causes  a  dollar  sign  to 

be  printed  to  the  immediate  left  of  the 
formatted  number.  The  $$  specifies  two 
more  digit  positions,  one  of  which  is  the 
dollar  sign.  The  exponential  format 
cannot  be  used  with  $$.  Negative  numbers 
cannot  be  used  unless  the  minus  sign  trails 
to  the  right. 


**$  The  **$  at  the  beginning  of  a  format  string 

combines  the  effects  of  the  above  two 
symbols.  Leading  spaces  are  filled  with 
asterisks  and  a  dollar  sign  will  be  printed 
before  the  number.  **$  specifies  three 
more  digit  positions,  one  of  which  is  the 
dollar  sign. 


A  comma  that  is  to  the  left  of  the  decimal 
point  in  a  formatting  string  causes  a 
comma  to  be  printed  to  the  left  of  every 
third  digit  to  the  left  of  the  decimal  point. 
A  comma  that  is  at  the  end  of  the  format 
string  is  printed  as  part  of  the  string.  A 
comma  specifies  another  digit  position. 
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PRINT  USING 
Statement 


The  comma  has  no  effect  if  used  with  the 
exponential  format. 

!"K  !  NT  US  !  Nh   11  ,  .     ■'  :  \  A]^. 


i, 


r>0 


1 1  'in  ■ 

Four  carets  may  be  placed  after  the  digit 
position  characters  to  specify  exponential 
format.  The  four  carets  allow  space  for 
E±nn  or  D±nn  to  be  printed.  Any  decimal 
point  position  may  be  specified.  The 
significant  digits  are  left-justified,  and  the 
exponent  is  adjusted.  Unless  a  leading  +  or 
trailing  +  or  -  is  specified,  one  digit 
position  is  used  to  the  left  of  the  decimal 
point  to  print  a  space  or  a  minus  sign. 


An  underscore  in  the  format  string  causes 
the  next  character  to  be  output  as  a  literal 
character. 

P R  INT  USING  '     !    -  .        [";]?.  y> 
J  12.3m! 

The  literal  character  itself  may  be  an 

underscore  by  placing  "  "  in  the  format 

string. 
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PRINT  USING 
Statement 


If  the  number  to  be  printed  is  larger  than  the 
specified  numeric  field,  a  percent  sign  (%)  is  printed 
in  front  of  the  number.  If  rounding  causes  the 
number  to  exceed  the  field,  the  percent  sign  is 
printed  in  front  of  the  rounded  number. 


Ok 

PRINT  US  I  NG  11  1  .  22 

111.22 
Ok 

PRINT  USING  .999 
1  .00 

Ok 


If  the  number  of  digits  specified  exceeds  24,  an 
"Illegal  function  call"  error  occurs. 


Example:   This  example  shows  how  you  can  include  string 
constants  in  the  format  string. 

Ok 

PRINT  US  I  NG  "THIS    IS  E  XAMP L  E     ■  • "  ;  1 

THIS    IS  EXAMPLE  1 

Ok 
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PRINT  #  and  PRINT  #  USING 

Statements 


Purpose:     Writes  data  sequentially  to  a  file. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:     PRINT    # filenum,  [USING  v$\]  list  of  exps 


Remarks:  filenum 


v$ 


is  the  number  used  when  the  file  was 
opened  for  output. 

is  a  string  expression  comprised  of 
formatting  characters  as  described  in  the 
previous  section,  "PRINT  USING 
Statement." 


list  of  exps  is  a  list  of  the  numeric  and/or  string 

expressions  that  will  be  written  to  the  file. 

PRINT  #  does  not  compress  data  on  the  file.  An 
image  of  the  data  is  written  to  the  file  just  as  it  would 
be  displayed  on  the  screen  with  a  PRINT  statement. 
For  this  reason,  care  should  be  taken  to  delimit  the 
data  on  the  file,  so  that  it  will  be  input  correctly  from 
the  file: 

In  the  list  of  expressions,  numeric  expressions 
should  be  delimited  by  semicolons.  For  example, 


PR  I  NT 


,A;B;C:X;Y;Z 


(If  commas  are  used  as  delimiters,  the  extra  blanks 
that  are  inserted  between  print  fields  are  also 
written  to  the  file.) 
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PRINT  #  and  PRINT  #  USING 
Statements 


String  expressions  must  be  separated  by  semicolons 
in  the  list.  To  format  the  string  expressions 
correctly  on  the  file,  use  explicit  delimiters  in  the 
list  of  expressions. 

For  example,  let  A$="CAMERA"  and 
B$="93604-l".  The  statement 

PRINT  ■■■  1  ,A$  ;  BS 

would  write  CAMERA93604-1  to  the  file.  Because 
there  are  no  delimiters,  this  could  not  be  input  as 
two  separate  strings.  To  correct  the  problem,  insert 
explicit  delimiters  into  the  PRINT  #  statement  as 
follows: 

D  R  I  NT   ••  !  ,A$;!Y:;BG 

The  image  written  to  the  file  is 

which  can  be  read  back  into  two  string  variables. 

If  the  strings  themselves  contain  commas, 
semicolons,  significant  leading  blanks,  carriage 
returns,  or  line  feeds,  write  them  to  the  file 
surrounded  by  explicit  quotation  marks  using 
CHR$(34). 

For  example,  let  A$="CAMERA,  AUTOMATIC" 
and  B$="    93604-1".  The  statement: 
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writes  the  following  image  to  the  file: 

!..\h^.-.  (         ro.MAT  i  (.        9  3  b  0  A  -  : 

and  the  statement: 

f  NP'm      1      J  ,  BS 

inputs  the  string  "CAMERA"  to  A$  and 
"AUTOMATIC      93604-1"  to  B$. 


PRINT  #  and  PRINT  #  USING 

Statements 


To  separate  these  strings  properly  on  the  file,  write 
double  quotes  to  the  file  image  using  CHR$(34). 
The  statement: 

PRINT     1  ,CHR$(3A)  ;A$;CHR$(3M  ;CHR$  (  3M  ; 
BS;CHR$  (3*0 

writes  the  following  image  to  the  file: 

"CAMFRA,   AUTOMAT  IT" "      9  360 'i  -  }  :  1 
and  the  statement: 

INPUT  ■■■  1  ,  A$  ,  BS 

inputs  "CAMERA,  AUTOMATIC"  to  A$  and 
"    93604-1"  to  B$. 

The  PRINT  #  statement  may  also  be  used  with  the 
USING  option  to  control  the  format  of  the  file.  For 
example: 

PR  INT  -1  ,  USING"  $$-      .      ,  "  :  J  ;K;L 

The  easy  way  to  avoid  all  these  problems  is  to  use  the 
WRITE  #  statement  rather  than  the  PRINT  # 
statement.  (Refer  to  "WRITE  #  Statement,"  at  the 
end  of  this  chapter.) 


Example:    For  more  examples  using  PRINT  #  and  WRITE  #, 
see  "Appendix  B.  BASIC  Diskette  Input  and 
Output." 
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PSET  and  PRESET 
Statements 


Purpose:     Draws  a  point  at  the  specified  position  on  the 
screen. 


Versions:    Cassette      Disk      Advanced  Compiler 


Graphics  mode  only. 

Format:      PSET  (x,y)  [,color] 

PRESET  (x,y)  [.color] 


Remarks:  {x,y) 


color 


are  the  coordinates  of  the  point  to  be  set. 
They  may  be  in  absolute  or  relative  form, 
as  explained  in  the  section  "Specifying 
Coordinates"  under  "Graphics  Modes"  in 
Chapter  3- 

specifies  the  color  to  be  used,  in  the  range 
0  to  3-  In  medium  resolution,  color  selects 
the  color  from  the  current  palette  as 
defined  by  the  COLOR  statement.  0  is  the 
background  color.  The  default  is  the 
foreground  color,  color  number  3.  In  high 
resolution,  a  color  of  0  (zero)  indicates 
black,  and  the  default  of  1  (one)  indicates 
white.  In  high  resolution  a  color  value  of  2 
will  be  treated  as  0,  and  3  will  be  treated  as 
1. 


PRESET  is  almost  identical  to  PSET.  The  only 
difference  is  that  if  no  color  parameter  is  given  to 
PRESET,  the  background  color  (0)  is  selected.  If 
color  is  included,  PRESET  is  identical  to  PSET.  Line 
70  in  the  example  below  could  just  as  easily  be: 


70  PSET  (  I 


3 
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PSET  and  PRESET 
Statements 


If  an  out  of  range  coordinate  is  given  to  PSET  or 
PRESET  no  action  is  taken  nor  is  an  error  given.  If 
color  is  greater  than  3,  this  will  result  in  an  "Illegal 
function  call"  error. 


Example:    Lines  20  through  40  of  this  example  draw  a  diagonal 
line  from  the  point  (0,0)  to  the  point  (100,100). 
Then  lines  60  through  80  erase  the  line  by  setting 
each  point  to  a  color  of  0. 


10  SCREEN  I 

20  FOR    1=0  TO  U 

30  PSET  (1,1) 

^0  NEXT 

5$  'erase  line 

60  FOR   1=100  TO 

70  PRESET  (|,|  ,! 

30  NEXT 


.TEP  - 
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PUT 

Statement  (Files) 


Purpose:     Writes  a  record  from  a  random  buffer  to  a  random 
file. 


Versions:    Cassette      Disk      Advanced  Compiler 

**  *  **  *  *** 


Format:      PUT  [#]  filenum  [,number\ 

Remarks:  filenum     is  the  number  under  which  the  file  was 
opened. 

number     is  the  record  number  for  the  record  to  be 
written,  in  the  range  1  to  32767. 

If  number  is  omitted,  the  record  has  the  next 
available  record  number  (after  the  last  PUT). 

PRINT  #,  PRINT  #  USING,  WRITE  #,  LSET,  and 
RSET  may  be  used  to  put  characters  in  the  random 
file  buffer  before  a  PUT  statement.  In  the  case  of 
WRITE  #,  BASIC  pads  the  buffer  with  spaces  up  to 
the  carriage  return. 

Any  attempt  to  read  or  write  past  the  end  of  the 
buffer  causes  a  "Field  overflow"  error.  Refer  to 
"Appendix  B.  BASIC  Diskette  Input  and  Output." 

Because  BASIC  and  DOS  block  as  many  records  as 
possible  in  512  byte  sectors,  the  PUT  statement 
does  not  necessarily  perform  a  physical  write  to  the 
diskette. 
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PUT 

Statement  (Files) 


PUT  can  be  used  for  a  communications  file.  In  that 
case  number  is  the  number  of  bytes  to  write  to  the 
communications  file.  This  number  must  be  less  than 
or  equal  to  the  value  set  by  the  LEN  option  on  the 
OPEN  "COM...  statement. 


Example:    See  "Appendix  B.  BASIC  Diskette  Input  and 
Output." 


> 
m 
m 
H 
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PUT 

Statement  (Graphics) 


Purpose:     Writes  colors  onto  a  specified  area  of  the  screen. 


Versions:    Cassette  Disk 


Advanced 
*** 


Compiler 


Graphics  mode  only. 


Format:      PUT  (x,y)  ,array  \,action\ 


Remarks:  (x,y) 


array 


are  the  coordinates  of  the  top  left  corner 
of  the  image  to  be  transferred. 

is  the  name  of  a  numeric  array  containing 
the  information  to  be  transferred.  See 
"GET  Statement  (Graphics)"  in  this 
chapter  for  more  information  on  this 
array. 


action 


is  one  o 


f: 


PSET 

PRESET 

XOR 

OR 

AND 


XOR  is  the  default. 

PUT  is  the  opposite  of  GET  in  the  sense  that  it  takes 
data  out  of  the  array  and  puts  it  onto  the  screen. 
However  it  also  provides  the  option  of  interacting 
with  the  data  already  on  the  screen  by  the  use  of  the 
action. 
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PUT 

Statement  (Graphics) 

PSET  as  an  action  simply  stores  the  data  from  the 
array  onto  the  screen,  so  this  is  the  true  opposite  of 
GET. 


PRESET  is  the  same  as  PSET  except  a  negative 
image  is  produced.  That  is,  a  value  of  0  in  the  array 
causes  the  corresponding  point  to  have  color 
number  3,  and  vice  versa;  a  value  of  1  in  the  array 
causes  the  corresponding  point  to  have  color 
number  2,  and  vice  versa. 


AND  is  used  when  you  want  to  transfer  the  image 
only  if  an  image  already  exists  under  the  transferred 
image. 

OR  is  used  to  superimpose  the  image  onto  the 
existing  image. 

XOR  is  a  special  mode  which  may  be  used  for 
animation.  XOR  causes  the  points  on  the  screen  to 
be  inverted  where  a  point  exists  in  the  array  image. 
XOR  has  a  unique  property  that  makes  it  especially 
useful  for  animation:  when  an  image  is  PUT  against 
a  complex  background  twice,  the  background  is 
restored  unchanged.  This  allows  you  to  move  an 
object  around  without  obliterating  the  background. 

In  medium  resolution  mode,  AND,  XOR,  and  OR 
have  the  following  effects  on  color: 
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OR 


array  value 
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Animation  of  an  object  can  be  performed  as  follows: 

1.  PUT  the  object  on  the  screen  (with  XOR). 

2.  Recalculate  the  new  position  of  the  object. 

3.  PUT  the  object  on  the  screen  (with  XOR)  a 
second  time  at  the  old  location  to  remove  the 
old  image. 

4.  Go  to  step  1,  this  time  putting  the  object  at  the 
new  location. 
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Movement  done  this  way  leaves  the  background 
unchanged.  Flicker  can  be  reduced  by  minimizing 
the  time  between  steps  4  and  1,  and  making  sure 
there  is  enough  time  delay  between  steps  1  and  3-  If 
more  than  one  object  is  being  animated,  every 
object  should  be  processed  at  once,  one  step  at  a 
time. 


If  it  is  not  important  to  preserve  the  background, 
animation  can  be  performed  using  the  PSET  action 
verb.  But  you  should  remember  to  have  an  image 
area  that  will  contain  the  "before"  and  "after" 
images  of  the  object.  This  way  the  extra  area  will 
effectively  erase  the  old  image.  This  method  may  be 
somewhat  faster  than  the  method  using  XOR 
described  above,  since  only  one  PUT  is  required  to 
move  an  object  (although  you  must  PUT  a  larger 
image). 


If  the  image  to  be  transferred  is  too  large  to  fit  on 
the  screen,  an  "Illegal  function  call"  error  occurs. 
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RANDOMIZE 
Statement 


Purpose:     Reseeds  the  random  number  generator. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:     RANDOMIZE  [«] 

Remarks:   n      is  an  integer  expression  which  will  be  used  as 
the  random  number  seed. 

If  n  is  omitted,  BASIC  suspends  program  execution 
and  asks  for  a  value  by  displaying: 

before  executing  RANDOMIZE. 

If  the  random  number  generator  is  not  reseeded,  the 
RND  function  returns  the  same  sequence  of 
random  numbers  each  time  the  program  is  run.  To 
change  the  sequence  of  random  numbers  every  time 
the  program  is  run,  place  a  RANDOMIZE 
statement  at  the  beginning  of  the  program  and 
change  the  seed  with  each  run. 

In  Disk  and  Advanced  BASIC,  the  internal  clock  can 
be  a  useful  way  to  get  a  random  number  seed.  You 
can  use  VAL  to  change  the  last  two  digits  of  TIME$ 
to  a  number,  and  use  that  number  for  n. 
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Statement 


Example:    10  RANDOM!  ZE 

20  FOR   1=1  TO  4 
30  PRINT  RND; 
kfl  NEXT  I 
RUN 

Random  Number  Seed   '-32768  to  32767)? 

Suppose  you  respond  with  3.  The  program 
continues: 

Random  Number  Seed   (-32768  to  32767'?  3 
.7655695     .3558607     .37^2327  .1388798 
Ok 
RUN 

Random  Number  Seed    '.-32768   to  32767)  ? 

Suppose  this  time  you  respond  with  4.  The  program 
continues: 

Random  Number   Seed    (-32768   to   32767)?  k 

.1719568      .5273236      .6879686  .713297 
Ok 
RUN 

Random  Number  Seed    i  -  32  ?68   to  3  2767  -!  7 

If  you  try  3  again,  you'll  get  the  same  sequence  as  the 
first  run: 

Random  Numbe-  Seed   (-32768  in  32767)?  3 
.7655695     .3558607     -  37^2327  .1338798 
Ok 
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READ 
Statement 


Purpose:  Reads  values  from  a  DATA  statement  and  assigns 
them  to  variables  (see  "DATA  Statement"  in  this 
chapter). 


Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 

Format:      READ  variable  [,  variable}... 


Remarks:    variable    is  a  numeric  or  string  variable  or  array 

element  which  is  to  receive  the  value  read 
from  the  DATA  table. 


A  READ  statement  must  always  be  used  in 
conjunction  with  a  DATA  statement.  READ 
statements  assign  DATA  statement  values  to  the 
variables  in  the  READ  statement  on  a  one-to-one 
basis.  READ  statement  variables  may  be  numeric  or 
string,  and  the  values  read  must  agree  with  the 
variable  types  specified.  If  they  do  not  agree,  a 
"Syntax  error"  will  result. 

A  single  READ  statement  may  access  one  or  more 
DATA  statements  (they  will  be  accessed  in  order),  or 
several  READ  statements  may  access  the  same 
DATA  statement.  If  the  number  of  variables  in  the 
list  of  variables  exceeds  the  number  of  elements  in 
the  DATA  statement(s),  an  "Out  of  data"  error 
occurs.  If  the  number  of  variables  specified  is  fewer 
than  the  number  of  elements  in  the  DATA 
statement(s),  subsequent  READ  statements  will 
begin  reading  data  at  the  first  unread  element.  If 
there  are  no  subsequent  READ  statements,  the 
extra  data  is  ignored. 
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To  reread  data  from  any  line  in  the  list  of  DATA 
statements,  use  the  RESTORE  statement  (see 
"RESTORE  Statement"  in  this  chapter). 


Example: 


This  program  segment  reads  the  values  from  the 
DATA  statements  into  the  array  A.  After  execution, 
the  value  of  A(l)  is  3.08,  and  so  on. 


This  program  reads  string  and  numeric  data  from 
the  DATA  statement  in  line  30.  Note  that  you  don't 
need  quotation  marks  around  COLORADO, 
because  it  doesn't  have  commas,  semicolons,  or 
significant  leading  or  trailing  blanks.  However,  vnn 
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Statement 


Purpose:     Inserts  explanatory  remarks  in  a  program. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  *** 


Format:      REM  remark 


Remarks:    remark      may  be  any  sequence  of  characters. 

REM  statements  are  not  executed  but  are  output 
exactly  as  entered  when  the  program  is  listed. 
However,  they  do  slow  up  execution  time 
somewhat,  and  take  up  space  in  memory. 

REM  statements  may  be  branched  into  (from  a 
GOTO  or  GOSUB  statement),  and  execution 
continues  with  the  first  executable  statement  after 
the  REM  statement. 

Remarks  may  be  added  to  the  end  of  a  line  by 
preceding  the  remark  with  a  single  quotation  mark 
instead  of  :REM.  If  you  put  a  remark  on  a  line  with 
other  BASIC  statements,  the  remark  must  be  the  last 
statement  on  the  line. 


Example:    I  00  P,  E  M  c  a  1  c  u  1  a  t  e  ti  v-eracj  e  ve!<>ci  t  y 
1  1 0   SUM=0 :    REM   initial  i  ze  SUM 
120  FOR    1-1   T 0  20 
! 30   SUM=SUM   +   V i  I ) 


Line  110  might  also  be  written: 

1  i  0  SUM--=0    1    i  r.  i  t  i  a  i  i  ze  SUM 
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RENUM 
Command 


Purpose:     Renumbers  program  lines. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      RENUM  [newnum]  [,[oldnum]  ^increment}} 


Remarks:  newnum 


is  the  first  line  number  to  be  used  in  the 
new  sequence.  The  default  is  10. 


oldnum      is  the  line  in  the  current  program  where 
renumbering  is  to  begin.  The  default  is  the 
first  line  of  the  program. 

increment  is  the  increment  to  be  used  in  the  new 
sequence.  The  default  is  10. 

RENUM  also  changes  all  line  number  references 
following  GOTO,  GOSUB,  THEN,  ELSE, 
ON.. .GOTO,  ON.. .GOSUB,  RESTORE, 
RESUME,  and  ERL  test  statements  to  reflect  the 
new  line  numbers.  If  a  nonexistent  line  number 
appears  after  one  of  these  statements,  the  error 
message  "Undefined,  line  number  xxxxx  in  yyyyy"  is 
printed.  The  incorrect  line  number  reference 
(xxxxx)  is  not  changed  by  RENUM,  but  line 
number  yyyyy  may  be  changed. 

Note:    RENUM  cannot  be  used  to  change  the 
order  of  program  lines  (for  example,  RENUM 
15,30  when  the  program  has  three  lines 
numbered  10,  20  and  30)  or  to  create  line 
numbers  greater  than  65529-  An  "Illegal 
function  call"  error  will  result. 
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Example:  RENUM 

Renumbers  the  entire  program.  The  first  new  line 
number  is  10.  Lines  increment  by  10. 

R.LNUM   300  ,  ,  50 

Renumbers  the  entire  program.  The  first  new  line 
number  is  300.  Lines  increment  by  50. 

RENUM  1000,300,20 

Renumbers  the  lines  from  900  up  so  they  start  with 
line  number  1000  and  increment  by  20. 
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RESET 
Command 


Purpose:     Closes  all  diskette  files  and  clears  the  system  buffer. 


Versions:    Cassette      Disk      Advanced  Compiler 

***  ***  *** 


Format:  RESET 


Remarks:    If  all  open  files  are  on  diskette,  then  RESET  is  the 
same  as  CLOSE  with  no  file  numbers  after  it. 


C/5 

H 

> 

m 

tn 
Z 
H 
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RESTORE 
Statement 


Purpose:     Allows  DATA  statements  to  be  reread  from  a 
specified  line. 

Versions:    Cassette      Disk      Advanced  Compiler 
**#  ***  ###  **# 


Format:      RESTORE  [line] 

Remarks:   line  is  the  line  number  of  a  DATA  statement  in 

the  program. 

After  a  RESTORE  statement  is  executed,  the  next 
READ  statement  accesses  the  first  item  in  the  first 
DATA  statement  in  the  program.  If  line  is  specified, 
the  next  READ  statement  accesses  the  first  item  in 
the  specified  DATA  statement. 

Example:  Ok 

10  Mi. AD  a,  3,0 

20  klSFORF. 

30  READ  D , I , F 

-'•0  Dm  FA  57,  68,  79 

50  PRINT  A ; B ; C ; D ; r ; r 
PUN 

vj!    68    79    57    68  79 

Ok 

The  RESTORE  statement  in  line  20  resets  the 
DATA  pointer  to  the  beginning,  so  that  the  values 
that  are  read  in  line  30  are  57,  68,  and  79. 
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RESUME 
Statement 


Purpose:     Continues  program  execution  after  an  error 
recovery  procedure  is  performed. 

Versions:    Cassette      Disk      Advanced  Compiler 


Format:      RESUME  [0] 

RESUME  NEXT 
RESUME  line 

Remarks:   Any  of  the  formats  shown  above  may  be  used, 
depending  upon  where  execution  is  to  resume: 


RESUME  NEXT  Execution  resumes  at  the 

statement  immediately  following 
the  one  which  caused  the  error. 

RESUME  line       Execution  resumes  at  the 
specified  line  number. 


(**) 


RESUME  or  RESUME  0 


Execution  resumes  at  the 
statement  which  caused  the 


error. 


Note:    If  you  try  to 
renumber  a  program 
containing  a  RESUME  0 
statement,  you  will  get  an 
"Undefined  line  number" 
error.  The  statement  will 
still  say  RESUME  0,  which  is 
okay. 
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Statement 


A  RESUME  statement  that  is  not  in  an  error  trap 
routine  causes  a  "RESUME  without  error"  message 
to  occur. 


Example: 


Line  900  is  the  beginning  of  the  error  trapping 
routine.  The  RESUME  statement  causes  the 
program  to  return  to  line  80  when  error  230  occurs 
in  line  90. 
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RETURN 
Statement 


Purpose:     To  bring  you  back  from  a  subroutine.  See  "GOSUB 
and  RETURN  Statements"  in  this  chapter. 


Versions:    Cassette      Disk      Advanced  Compiler 


line  valid  only  in  Advanced  and  Compiler. 


Format:      RETURN  [line] 


Remarks:  line 


is  the  line  number  of  the  program  line  you 
wish  to  return  to.  You  may  use  it  only  in 
Advanced  BASIC. 


Although  you  can  use  RETURN  line  to  return  from 
any  subroutine,  this  enhancement  was  added  to 
allow  non-local  returns  from  the  event  trapping 
routines.  From  one  of  these  routines  you  will  often 
want  to  go  back  to  the  BASIC  program  at  a  fixed  line 
number  while  still  eliminating  the  GOSUB  entry  the 
trap  created.  Use  of  the  non-local  RETURN  must  be 
done  with  care,  however,  since  any  other  GOSUBs, 
WHILEs,  or  FORs  that  were  active  at  the  time  of  the 
trap  will  remain  active. 
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RIGHT$ 
Function 


Purpose:  Returns  the  rightmost  n  characters  of  string  x$. 
Versions:    Cassette      Disk      Advanced  Compiler 


Format:     v$  =  RIGHT$(jr#,/?) 


Remarks:   x$     is  any  string  expression. 

n      is  an  integer  expression  specifying  the  number 
of  characters  to  be  in  the  result. 

If  n  is  greater  than  or  equal  to  LEN(.r$),  then  x$  is 
returned.  If  n  is  zero,  the  null  string  (length  zero)  is 
returned. 

Also  see  the  MID$  and  LEFTS  functions. 


Example:  Ok 

10  AS="B0CA  RATON,  FLORIDA 
20   PR  I  IU    RIGHTS (AS,  7; 
RUN 

f LOR! Dm 


The  rightmost  seven  characters  of  the  string  A$  are 
returned. 
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RND 
Function 


Purpose:     Returns  a  random  number  between  0  and  1. 


Versions:    Cassette     Disk      Advanced  Compiler 


Format:      v  =  RND[(j)] 


Remarks:  x      is  a  numeric  expression  which  affects  the 
returned  value  as  described  below. 

The  same  sequence  of  random  numbers  is  generated 
each  time  the  program  is  run  unless  the  random 
number  generator  is  reseeded.  This  is  most  easily 
done  using  the  RANDOMIZE  statement  (see 
"RANDOMIZE  Statement"  in  this  chapter).  You 
may  also  reseed  the  generator  when  you  call  the 
RND  function  by  using  x  where  x  is  negative.  This 
always  generates  the  particular  sequence  for  the 
given  x.  This  sequence  is  not  affected  by 
RANDOMIZE,  so  if  you  want  to  generate  a  different 
sequence  each  time  the  program  is  run,  you  must 
use  a  different  value  for  x  each  time. 


Ifx  is  positive  or  not  included,  RND(r)  generates  the 
next  random  number  in  the  sequence. 

RND(O)  repeats  the  last  number  generated. 

To  get  random  numbers  in  the  range  0  (zero) 
through  n,  use  the  formula: 

INT(  RND  *  (*+l)) 


4-249 


RND 
Function 


Example:  Ok 

10 
20 

30 
40 
50 
60 
70 
80 
90 
10( 


1  10 
120 

130 
RUN 
.  629 


FOR  1=1  TO  3 

PRINT  RND( I ) ;  1   x  0 

NEXT  I 

PRI  NT  :   X=RND  (-6)    1   x-  0 
FOR   1-1  TO  3 
PRINT  RND ( I ) ;  1    x  0 

NEXT  I 

RANDOM  I ZE  85  3   1  randomi ze 
PRINT:   X=RND(-6)    1    x- 0 
FOR   1=1   TO  3 

RND;        1    same  as  x  -0 


PRI  NT 

NEXT 
PRI  NT 


PRINT  RND  (0; 


626 
681861 5 
6818615 
6215937 


1948297 
41 93624 
4193624 


.6305799 
.6215937 
.6215937 


Ok 


The  first  horizontal  line  of  results  shows  three 
random  numbers,  generated  using  a  positive  x. 

In  line  40,  a  negative  number  is  used  to  reseed  the 
random  number  generator.  The  random  numbers 
produced  after  this  seeding  are  in  the  second  row  of 
results. 


In  line  80,  the  random  number  generator  is  reseeded 
using  the  RANDOMIZE  statement;  in  line  90  it  is 
reseeded  again  by  calling  RND  with  the  same 
negative  value  we  used  in  line  40.  This  cancels  the 
effect  of  the  RANDOMIZE  statement,  as  you  can 
see;  the  third  line  of  results  is  identical  to  the  second 
line. 


In  line  1  30,  RND  is  called  with  an  argument  of  zero, 
so  the  last  number  printed  is  the  same  as  the 
preceding  number. 
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RUN 
Command 


Purpose:     Begins  execution  of  a  program. 


Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  ^**^ 

Format:      RUN  [line] 

RUN//fer/w[,R] 


Remarks:  line 


filespec 


is  the  line  number  of  the  program  in 
memory  where  you  wish  execution  to 
begin. 

is  a  string  expression  for  the  file 
specification,  as  explained  under  "Naming 
Files"  in  Chapter  3.  The  default  extension 
.BAS  is  supplied  for  diskette  files. 


RUN  or  RUN  line  begins  execution  of  the  program 
currently  in  memory.  If  line  is  specified,  execution 
begins  with  the  specified  line  number.  Otherwise, 
execution  begins  at  the  lowest  line  number. 

RUN  filespec  loads  a  file  from  diskette  or  cassette 
into  memory  and  runs  it.  It  closes  all  open  files  anc 
deletes  the  current  contents  of  memory  before 
loading  the  designated  program.  However,  with  th< 
R  option,  all  data  files  remain  open.  Refer  also  to 
"Appendix  B.  BASIC  Diskette  Input  and  Output.' 

Executing  a  RUN  command  will  turn  off  any  sounc 
that  is  running  and  reset  to  Music  Foreground.  Also 
PEN  and  STRIG  will  be  reset  to  OFF. 
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RUN 

Command 

Example:  ° 


In  this  first  example,  we  use  the  first  form  of  RUN 
on  two  very  small  programs.  The  first  program  is  run 
from  the  beginning.  We  used  the  RUN  line  option 
for  the  second  example  to  run  the  program  from 
line  20.  In  this  case,  line  10  does  not  get  executed,  so 
PI  does  not  receive  its  proper  value.  A  0  is  printed 
because  all  numeric  variables  have  an  initial  value  of 
zero. 

R1  ;•.  :  CAC  1  :NFWn  L"  ,R 

The  preceding  example  loads  the  program 
"NEWFIL"  from  the  tape  and  runs  it,  keeping  files 
open. 
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SAVE 
Command 


Purpose:     Saves  a  BASIC  program  file  on  diskette  or  cassette. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      SAVE  file  spec  [,A] 
SAVE  filespec  [,P] 


Remarks:  filespec 


is  a  string  expression  for  the  file 
specification.  If filespec  does  not  conform 
to  the  rules  outlined  under  "Naming  Files" 
in  Chapter  3,  an  error  is  issued  and  the  save 
is  cancelled. 


The  BASIC  program  is  written  to  the  specified 
device.  When  saving  to  CASl:,  the  cassette  motor  is 
turned  on  and  the  file  is  immediately  written  to  the 
tape. 

For  diskette  files,  if  the  filename  is  eight  characters 
or  less  and  no  extension  is  supplied,  the  extension 
.BAS  is  added  to  the  name.  If  a  file  with  the  same 
filename  already  exists  on  the  diskette,  it  will  be 
written  over. 

When  using  Cassette  BASIC,  if  the  device  name  is 
omitted,  CASl:  is  assumed.  CASl:  is  the  only 
allowable  device  for  SAVE  in  Cassette  BASIC. 

For  Disk  and  Advanced  BASIC,  the  device  defaults 
to  the  DOS  default  drive. 

The  A  option  saves  the  program  in  ASCII  format. 
Otherwise,  BASIC  saves  the  file  in  a  compressed 
binary  (tokenized)  format.  ASCII  files  take  up  more 
space,  but  some  types  of  access  require  that  files  be 
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SAVE 
Command 


in  ASCII  format.  For  example,  a  file  intended  to  be 
merged  must  be  saved  in  ASCII  format.  Programs 
saved  in  ASCII  may  be  read  as  data  files. 

The  P  option  saves  the  program  in  an  encoded 
binary  format.  This  is  the  protection  option.  When 
a  protected  program  is  later  run  (or  loaded),  any 
attempt  to  LIST  or  EDIT  it  fails  with  an  "Illegal 
function  call"  error.  No  way  is  provided  to 
"unprotect"  such  a  program. 

Note:    The  diskette  directory  entry  for  a 
BASIC  program  file  gives  no  indication  that  the 
file  is  either  protected  or  stored  in  ASCII 
format.  The  .BAS  extension  is  used  in  any  case. 

See  also  "Appendix  B.  BASIC  Diskette  Input  and 
Output." 

Example:    SAVE  "INVENT" 

Saves  the  program  in  memory  as  INVENT.  The 
program  is  saved  on  cassette  if  you  are  using 
Cassette  BASIC.  If  you  are  using  Disk  or  Advanced 
BASIC,  the  program  is  saved  on  the  diskette  in  the 
DOS  default  drive  and  given  an  extension  of  .BAS. 

SAVE  "B: PROG", A 

Saves  PROG. BAS  on  drive  B:  in  ASCII,  so  it  may 
later  be  merged. 

SAVE  "A:SECRET.BOZ",P 

Saves  SECRET. BOZ  on  drive  A:,  protected  so  it  may 
not  be  altered. 
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SCREEN 
Function 

X.    U  X  p  WOV>.  ij.^  

the  active  screen  at  the  specified  row  (line)  and 
column. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 

Format:     v  =  $CREEN(row,col[,z]) 

Remarks:   row  is  a  numeric  expression  in  the  range  1  to  25. 

col    is  a  numeric  expression  in  the  range  1  to  40  or  1 
to  80  depending  upon  the  WIDTH  setting. 

z      is  a  numeric  expression  which  evaluates  to  a 
true  or  false  value,  z  is  only  valid  in  text  mode. 

Refer  to  "Appendix  G.  ASCII  Character  Codes"  for 
a  list  of  ASCII  codes. 

In  text  mode,  if  z  is  included  and  is  true  (non-zero), 
the  color  attribute  for  the  character  is  returned 
instead  of  the  code  for  the  character.  The  color 
attribute  is  a  number  in  the  range  0  to  255.  This 
number,  v,  may  be  deciphered  as  follows: 

(v  MOD  16)  is  the  foreground  color. 

{{(v  -  foreground)/ \6)  MOD  128)  is  the  background 
color,  where  foreground  is  calculated  as  above. 

(^>127)  is  true  (-1)  if  the  character  is  blinking, 
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SCREEN 
Function 


Refer  to  "COLOR  Statement"  for  a  list  of  colors  and 
their  associated  numbers. 

In  graphics  mode,  if  the  specified  location  contains 
graphic  information  (points  or  lines,  as  opposed  to 
just  a  character),  then  the  SCREEN  function  returns 
zero. 

Any  values  entered  outside  of  the  ranges  indicated 
result  in  an  "Illegal  function  call"  error. 

The  SCREEN  statement  is  explained  in  the  next 
section. 


Example:    1 00  X  =  SCREEN  (10,10) 

If  the  character  at  10,10  is  A,  then  X  is  65- 

1 1 0  X   -  SCREEN  (1,1,1) 

Returns  the  color  attribute  of  the  character  in  the 
upper  left  hand  corner  of  the  screen. 
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SCREEN 
Statement 


Purpose:     Sets  the  screen  attributes  to  be  used  by  subsequent 
statements. 


Versions:    Cassette      Disk      Advanced  Compiler 
**  *  ***  **  *  *  *  * 


Meaningful  with  the  Color/Graphics  Monitor 
Adapter  only. 


Format:      SCREEN  [mode]  [,[burst]  [,[apage]  [,vpage]]] 


Remarks:   mode        is  a  numeric  expression  resulting  in  an 

integer  value  of  0,  1  or  2.  Valid  modes  are: 

0  Text  mode  at  current  width  (40  or 
80). 

1  Medium  resolution  graphics  mode 
(320x200).  Use  with  Color/Graphics 
Monitor  Adapter  only. 

2  High  resolution  graphics  mode 
(640x200).  Use  with  Color/Graphics 
Monitor  Adapter  only. 

burst        is  a  numeric  expression  resulting  in  a  true 
or  false  value.  It  enables  color.  In  text 
mode  (mode=0),  a  false  (zero)  value  disables 
color  (black  and  white  images  only)  and  a 
true  (non-zero)  value  enables  color  (allows 
color  images).  In  medium  resolution 
graphics  mode  (mode=\),  a  true  (non-zero) 
value  will  disable  color,  and  a  false  (zero) 
value  will  enable  color.  Since  black  and 
white  are  the  only  colors  in  high  resolution 
graphics  (mode=2),  this  parameter  will  not 
have  much  effect  in  high  resolution. 
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SCREEN 
Statement 


(active  page)  is  an  integer  expression  in  the 
range  0  to  7  for  width  40,  or  0  to  3  for 
width  80.  It  selects  the  page  to  be  written 
to  by  output  statements  to  the  screen,  and 
is  valid  in  text  mode  {mode=0)  only. 

(visual  page)  selects  which  page  is  to  be 
displayed  on  the  screen,  in  the  same  way  as 
apage  above.  The  visual  page  may  be 
different  than  the  active  page,  vpage  is  valid 
in  text  mode  (mode=0)  only.  If  omitted, 
vpage  defaults  to  apage. 

If  all  parameters  are  valid,  the  new  screen  mode  is 
stored,  the  screen  is  erased,  the  foreground  color  is 
set  to  white,  and  the  background  and  border  colors 
are  set  to  black. 

If  the  new  screen  mode  is  the  same  as  the  previous 
mode,  nothing  is  changed. 

If  the  mode  is  text,  and  only  apage  and  vpage  are 
specified,  the  effect  is  that  of  changing  display  pages 
for  viewing.  Initially,  both  active  and  visual  pages 
default  to  0  (zero).  By  manipulating  active  and  visual 
pages,  you  can  display  one  page  while  building 
another.  Then  you  can  switch  visual  pages 
instantaneously. 

If  you  mix  text  and  graphics  in  the  10  or  80  column 
graphics  mode  and  are  not  using  a  U.S.  keyboard,  refer  to 
"GRAFTABL-Color/Graphics  Adapter  Characters"  in 
the  DOS  section  of  the  Guide  to  Operations. 

Note:  There  is  only  one  cursor  shared 
between  all  the  pages.  If  you  are  going  to  switch 
active  pages  back  and  forth,  you  should  save  the 
cursor  position  on  the  current  active  page 
(using  POS(0)  and  CSRLIN),  before  changing 
to  another  active  page.  Then  when  you  return 
to  the  original  page,  you  can  restore  the  cursor 
position  using  the  LOCATE  statement. 
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SCREEN 
Statement 


Any  parameter  may  be  omitted.  Omitted 
parameters,  except  vpage,  assume  the  old  value. 

Any  values  entered  outside  of  the  ranges 
indicated  will  result  in  an  "Illegal  function  call" 
error.  Previous  values  are  retained. 

If  you  are  writing  a  program  which  is  intended 
to  be  run  on  a  machine  that  may  have  either 
adapter,  we  suggest  you  use  the  SCREEN  0,0,0 
and  WIDTH  40  statements  at  the  beginning  of 
the  program. 


Example:   10  SCREEN  0,1,0,0 


Selects  text  mode  with  color,  and  sets  active  and 
visual  page  to  0. 


20  SCREEN  ,,1,2 

Mode  and  color  burst  remain  unchanged.  Active 
page  is  set  to  1  and  display  page  to  2. 


30  SCREEN  2 , ,0 ,0 

Switches  to  high  resolution  graphics  mode. 


^0  SCREEN  1,0 

Switches  to  medium  resolution  color  graphics. 


50  SCREEN  ,1 

Sets  medium  resolution  graphics  with  color  off. 


4-259 


SGN 
Function 


Purpose:     Returns  the  sign  of  x. 

Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  *** 

Format:     v  =  SGN(x) 

Remarks:  x     is  any  numeric  expression. 

SGN(,r)  is  the  mathematical  signum  function: 

•  If  x  is  positive,  SGN(jr)  returns  1. 

•  If  x  is  zero,  SGN(.r)  returns  0. 

•  If  jf  is  negative,  SGN(.r)  returns  -1. 

Example:    ,\    ,;*,  ■  a   • ^o;u  i03,,:00,>^ 

branches  to  100  if  X  is  negative,  200  if  X  is  zero,  and 
300  if  X  is  positive. 
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SIN 
Function 


Purpose:     Calculates  the  trigonometric  sine  function. 
Versions:    Cassette      Disk      Advanced  Compiler 

Format:     v  =  SIN(jr) 

Remarks:   x     is  an  angle  in  radians. 

If  you  want  to  convert  degrees  to  radians,  multiply 
by  PI/180,  where  PI=3. 141593. 

SIN(;r)  is  calculated  in  single  precision. 

Example:  Ok 

10  P  I  =3  -  1 ^ 1 593  I 

20   DEGREES  =  90 

30  RAD  I  AN S- DEGREES    •  P  !  /  1  80    1    P  !  II 
^0  PRINT  S  J  N  f  RAD  I ANS) 

RUN  I 
1 

Ok 

This  example  calculates  the  sine  of  90  degrees,  after 
first  converting  the  degrees  to  radians. 
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SOUND 
Statement 


Purpose:     Generates  sound  through  the  speaker. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      SOUND  freq,  duration 


Remarks:  freq 


is  the  desired  frequency  in  Hertz  (cycles 
per  second).  It  must  be  a  numeric 
expression  in  the  range  37  to  32767. 


duration    is  the  desired  duration  in  clock  ticks.  The 
clock  ticks  occur  18.2  times  per  second. 
duration  must  be  a  numeric  expression  in 
the  range  0  to  65535. 

When  the  SOUND  statement  produces  a  sound,  the 
program  continues  to  execute  until  another 
SOUND  statement  is  reached.  If  duration  of  the  new 
SOUND  statement  is  zero,  the  current  SOUND 
statement  that  is  running  is  turned  off.  Otherwise, 
the  program  waits  until  the  first  sound  completes 
before  it  executes  the  new  SOUND  statement. 


If  you  are  using  Advanced  BASIC,  you  can  cause  the 
sounds  to  be  buffered  so  execution  does  not  stop 
when  a  new  SOUND  statement  is  encountered.  See 
the  MB  command  explained  under  "PLAY 
Statement"  in  this  chapter  for  details. 

If  no  SOUND  statement  is  running,  SOUNDjf,0  has 
no  effect. 
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SOUND 
Statement 


The  tuning  note,  A,  has  a  frequency  of  440.  The 
following  table  correlates  notes  with  their 
frequencies  for  two  octaves  on  either  side  of  middle 
C. 


INote 

frequency 

INote 

frequency 

G 

1  30.810 

L. 

523.250 

D 

146.830 

D 

587.330 

E 

164.810 

E 

659.260 

F 

174.610 

F 

698.460 

G 

196.000 

G 

783.990 

A 

220.000 

A 

880.000 

B 

246.940 

B 

987.770 

C 

261.630 

C 

1046.500 

D 

293.660 

D 

1174.700 

E 

329.630 

E 

1318.500 

F 

349.230 

F 

1396.900 

G 

392.000 

G 

1568.000 

A 

440.000 

A 

1760.000 

B 

493.880 

B 

1975.500 

*middle  C.  Higher  (or  lower)  notes  may  be 
approximated  by  doubling  (or  halving)  the 
frequency  of  the  corresponding  note  in  the  previous 
(next)  octave. 


To  create  periods  of  silence,  use  SOUND 
327 '67  Juration . 

The  duration  for  one  beat  can  be  calculated  from 
beats  per  minute  by  dividing  the  beats  per  minute 
into  1092  (the  number  of  clock  ticks  in  a  minute). 
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SOUND 
Statement 


The  next  table  shows  typical  tempos  in  terms  of 
clock  ticks: 


Tempo 

Beats/ 
Minute 

Ticks/ 
Beat 

very 

slow 

Larghissimo 

Largo 

40-60 

27.3-18.2 

Larghetto 

60-66 

18.2-16.55 

Grave 

Lento 

Adagio 

66-76 

16.55-14.37 

slow 

Adagietto 

t 

Andante 

76-108 

14.37-10.11 

medium 

Andantino 

\ 

\ 

Moderato 

108-120 

10.1 1-9.1 

fast 

Allegretto 

Allegro 

120-168 

9.1-6.5 

Vivace 

Veloce 

r 

Presto 

168-208 

6.5-5.25 

very 

fast 

Prestissimo 

Example:    The  following  program  creates  a 
glissando  up  and  down. 

10  FOR   I--Vt0  TO   1000      [:  f  5 

20  SOUND   I ,  0.5 

30  NEXT 

40  FOR    I -1000  TO  kh$   STEP  ~5 

50  SOUND     ,  0.5 

60  NEXT 


4-264 


SPACE$ 
Function 


Purpose:     Returns  a  string  consisting  of  n  spaces. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      v$  =  SPACE$(tf) 

Remarks:   n      must  be  in  the  range  0  to  255. 

Refer  also  to  the  SPC  function. 


Example: 


2  0    /  1     -       f:  C 

30  f-  K  I  \  I  XS; 
4  0  NCM  I 


This  example  uses  the  SPACES  function  to  print 
each  number  I  on  a  line  preceded  by  I  spaces.  An 
additional  space  is  inserted  because  BASIC  puts  a 
space  in  front  of  positive  numbers. 
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SPC 

Function 


Purpose:     Skips  n  spaces  in  a  PRINT  statement. 
Versions:    Cassette      Disk      Advanced  Compiler 


Format:      PRINT  SPC(») 

Remarks:   n      must  be  in  the  range  0  to  25  5. 

If  n  is  greater  than  the  defined  width  of  the  device, 
then  the  value  used  is  n  MOD  width.  SPC  may  only  be 
used  with  PRINT,  LPRINT  and  PRINT  # 
statements. 

If  the  SPC  function  is  at  the  end  of  the  list  of  data 
items,  then  BASIC  does  not  add  a  carriage  return,  as 
though  the  SPC  function  had  an  implied  semicolon 
after  it. 

Also  see  the  SPACE$  function. 

Example:  Ok 

PRINT  "OVER"  S  PC  C 1 5 )  "THERE" 
OVER  THERE 
Ok 

This  example  prints  OVER  and  THERE  separated 
by  15  spaces. 
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SQR 
Function 


Purpose:     Returns  the  square  root  of  x. 

Versions:    Cassette      Disk      Advanced  Compiler 


Format:     v  =  SQR(jt) 

Remarks:   x  must  be  greater  than  or  equal  to  zero. 


Example:  Ok 

10  FOR  X  =   1 0  TO  25  STEP  5 
20   PRINT  X,    S  QfU  X  ) 
30  NEXT 
RUN 

10  3.162278 
15  3  •  872984 

20  A  .^721 36 

25  5 
Ok 

This  example  calculates  the  square  roots  of  the 
numbers  10,  15,  20  and  25. 
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STICK 
Function 


Purpose:     Returns  the  x  and  y  coordinates  of  two  joysticks. 

Versions:    Cassette      Disk      Advanced  Compiler 
*#*  ***  ***  *** 


Format:      v  =  STICK(/?) 

Remarks:   n      is  a  numeric  expression  in  the  range  0  to  3 
which  affects  the  result  as  follows: 

0  returns  the  x  coordinate  for  joystick  A. 

1  returns  the  y  coordinate  of  joystick  A. 

2  returns  the  x  coordinate  of  joystick  B. 

3  returns  the  y  coordinate  of  joystick  B. 

Note:    STICK(O)  retrieves  all  four  values  for 
the  coordinates,  and  returns  the  value  for 
STICK(O).  STICK(I),  STICK(2),  and  STICK(3) 
do  not  sample  the  joystick.  They  get  the  values 
previously  retrieved  by  STICK  (0). 

The  range  of  values  for  x  and  y  depends  on  your 
particular  joysticks. 
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STICK 
Function 


Example:    10  PRINT  "Joystick  B ' 1 

20  PRINT  "x  coordinate","1/  coordinate" 
30  FOR  J=1   TO  100 

h$  1 EMP=ST I CK(0) 

50  >=ST I C  K ( 2 )  :    Y=ST I CK(3) 

60  PRINT  X,Y 

70  NEXT 

This  program  takes  100  samples  of  the  coordinates 
of  joystick  B  and  prints  them. 


C/5 

> 
m 

H 

C/5 
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STOP 
Statement 


Purpose:     Terminates  program  execution  and  returns  to 
command  level. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  /**\ 


Format:  STOP 


Remarks:    STOP  statements  may  be  used  anywhere  in  a 

program  to  terminate  execution.  When  BASIC 
encounters  a  STOP  statement,  it  displays  the 
following  message: 

B  reak   in  nnnnn 

where  nnnnn  is  the  line  number  where  the  STOP 
occurred. 

Unlike  the  END  statement,  the  STOP  statement 
does  not  close  files. 

BASIC  always  returns  to  command  level  after  it 
executes  a  STOP.  You  can  resume  execution  of  the 
program  by  issuing  a  CONT  command  (see  "CO NT 
Command"  in  this  chapter). 
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STOP 
Statement 


Example:    10  INPUT  A,  B 

20  1  i  :'F  -  A--B 
30  STOP 

40  FiNAL  =  TEMP+200:  print  final 
RUN 

?  26.  2.1 

Break   in  30 
Ok 

PR  I  NT  TEMP 
54.6 

Ok 

CONT 

254.6 
Ok 

This  example  calculates  the  value  of  TEMP,  then 
stops.  While  the  program  is  stopped,  we  can  check 
the  value  of  TEMP.  Then  we  can  use  CONT  to 
resume  program  execution  at  line  40. 


H 
> 
H 

m 

S 

m 
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STR$ 
Function 


Purpose:     Returns  a  string  representation  of  the  value  of  x. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:      v$  =  STR$(jr) 


Remarks:   x  is  any  numeric  expression. 

If  jr  is  positive,  the  string  returned  by  STR$  contains 
a  leading  blank  (the  space  reserved  for  the  plus  sign). 
For  example: 

Ok 

?   STRS  (32  1  J  ;    LEN (SIRS (321  )  ) 

32  1  4 
Ok 

The  VAL  function  is  complementary  to  STR$. 


Example:   This  example  branches  to  different  sections  of  the 
program  based  on  the  number  of  digits  in  a  number 
that  is  entered.  The  digits  in  the  number  are  counted 
by  using  STR$  to  convert  the  number  to  a  string, 
then  branching  based  on  the  length  of  the  string. 


5   RL  Y\  <-\ r  i  !  h^c  1  I  c    1  <  ■  r   k  i  ch 
10    INPUT   "ffPt   A  NUMBER"  ;N 

20  ON   I  EfJi  S1"PS  i'Nt  )- 1    GOSUB  30,100,200,300 
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STRIG 

Statement  and  Function 


Purpose:  Returns  the  status  of  the  joystick  buttons  (triggers). 
Versions:    Cassette      Disk      Advanced  Compiler 

Format:      As  a  statement: 
STRIG  ON 
STRIG  OFF 
As  a  function: 

v  =  STRIG(») 


Remarks:   n      is  a  numeric  expression  in  the  range  0  to  3.  It 
affects  the  value  returned  by  the  function  as 
follows: 

0  Returns -1  if  button  Al  was  pressed  since 
the  last  STRIG(O)  function  call,  returns  0 
if  not. 

1  Returns  -1  if  button  Al  is  currently 
pressed,  returns  0  if  not. 

2  Returns -1  if  button  Bl  was  pressed  since 
the  last  STRIG(2)  function  call,  returns  0 
if  not. 

3  Returns  -1  if  button  Bl  is  currently 
pressed,  returns  0  if  not. 
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STRIG 

Statement  and  Function 


In  Advanced  BASIC  and  the  BASIC  Compiler, 
you  can  read  four  buttons  from  the  joysticks. 
The  additional  values  for  n  are: 

4  Returns  -1  if  button  A2  was  pressed  since 
the  last  STRIG(4)  function  call,  returns  0 
if  not. 

5  Returns -1  if  button  A2  is  currently 
pressed,  returns  0  if  not. 

6  Returns  -1  if  button  B2  was  pressed  since 
the  last  STRIG(6)  function  call,  returns  0 
if  not. 

7  Returns  -1  if  button  B2  is  currently 
pressed,  returns  0  if  not. 

STRIG  ON  must  be  executed  before  any  STRIG(») 
function  calls  may  be  made.  After  STRIG  ON,  every 
time  the  program  starts  a  new  statement  BASIC 
checks  to  see  if  a  button  has  been  pressed. 

If  STRIG  is  OFF,  no  testing  takes  place. 

Refer  also  to  the  next  section,  "STRIG(n) 
Statement"  for  enhancements  to  the  STRIG 
function  in  Advanced  BASIC. 
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STRIG(n) 
Statement 


Purpose:     Enables  and  disables  trapping  of  the  joystick 
buttons. 


Versions:    Cassette      Disk  Advanced 


Compiler 
(**) 


Format:      STRIG(»)  ON 
STRIG(ff)  OFF 
STRIG(tf)  STOP 


Remarks:  n 


may  be  0,  2,  4,  or  6,  and  indicates  the  button  to 
be  trapped  as  follows: 


button  Al 
button  Bl 
button  A2 
button  B2 


STRIG(tf)  ON  must  be  executed  to  enable  trapping 
by  the  ON  STRIG(»)  statement  (see  "ON  STRIG(n) 
Statement"  in  this  chapter).  After  STRIG(z?)  ON, 
every  time  the  program  starts  a  new  statement, 
BASIC  checks  to  see  if  the  specified  button  has  been 
pressed. 


If  STRIG(tf)  OFF  is  executed,  no  testing  or  trapping 
takes  place.  Even  if  the  button  is  pressed,  the  event 
is  not  remembered. 


If  a  STRIG(#)  STOP  statement  is  executed,  no 
trapping  takes  place.  However,  if  the  button  is 
pressed  it  is  remembered  so  that  an  immediate  trap 
takes  place  when  STRIG(tf)  ON  is  executed. 

Refer  also  to  the  previous  section,  "STRIG 
Statement  and  Function." 


4-275 


STRING$ 
Function 


Purpose:     Returns  a  string  of  length  n  whose  characters  all 
have  ASCII  code  m  or  the  first  character  of  x$. 


Versions:    Cassette      Disk      Advanced  Compiler 


Format:     v$  =  STRING$(«,w) 
v$  =  STRING!  (n,x$) 


Remarks:   n,  m  are  in  the  range  0  to  255. 

x$    is  any  string  expression. 


Example:  ) 

10    v.3    =    S  T  R  i  N  G  S  i  10,  M  5  ! 

20   PRINT    X'j   "MONTHLY   REPORT"  XS 

 MOiUHL  V  REPORT  

Ok 

The  first  example  repeats  an  ASCII  value  of  45  to 
print  a  string  of  hyphens. 

0  r 

10  ;<3  =  "AbCD-i 

20   Y  S  -t-  5  T  R  i  ,N  G  S  (  10,XS.j 

30  PRINT  YS 

RUN 

mmMmAmAAa-V 
Ok 

The  second  example  repeats  the  first  character  of 
the  string  "ABCD". 
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Purpose: 
Versions: 


Format: 
Remarks: 


Example: 


SWAP 
Statement 

Exchanges  the  values  of  two  variables. 

Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 


SWAP  variablel,  variable2 


variablel,  variable2 

are  the  names  of  two  variables  or  array 
elements. 

Any  type  variable  may  be  swapped  (integer, 
single-precision,  double-precision,  string),  but  the 
two  variables  must  be  of  the  same  type  or  a  "Type 
mismatch"  error  results. 


Ok 

10  A$=M  ONE   m    :    B^="  ALL   "    :  CS="F0R" 
20  PRINT  AS  C$  BS 
30  SWAP  A$,  BS 
PR  I N  r  AS   CS  BS 

RUN 

ONE   FOR  ALL 
ALL   POL.  ONE 
Ok 

After  line  30  is  executed,  A$  has  the  value  "  ALL 
and  B$  has  the  value  "  ONE  ". 
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SYSTEM 
Command 


Purpose:     Exits  BASIC  and  returns  to  DOS. 

Versions:    Cassette      Disk      Advanced  Compiler 

***  ***  *** 


Format:  SYSTEM 


Remarks:    SYSTEM  closes  all  files  before  it  returns  to  DOS. 
Your  BASIC  program  is  lost. 

If  you  entered  BASIC  through  a  Batch  file  from 
DOS,  the  SYSTEM  command  returns  you  to  the 
Batch  file,  which  continues  executing  at  the  point  it 
left  off. 


i 
l 
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TAB 
Function 


Purpose:     Tabs  to  position  n. 

Versions:    Cassette     Disk      Advanced  Compiler 


*  *  *  *  ** 


Format:      PRINT  TAB(/z) 


Remarks:   n  must  be  in  the  range  1  to  255. 

If  the  current  print  position  is  already  beyond  space 
n,  TAB  goes  to  positions  on  the  next  line.  Space  1  is 
the  leftmost  position,  and  the  rightmost  position  is 
the  defined  WIDTH. 

TAB  may  only  be  used  in  PRINT,  LPRINT,  and 
PRINT  #  statements. 

If  the  TAB  function  is  at  the  end  of  the  list  of  data 
items,  then  BASIC  does  not  add  a  carriage  return,  as 
though  the  TAB  function  had  an  implied  semicolon 
after  it. 


Example:   TAB  is  used  in  the  following  example  to  cause  the 
information  on  the  screen  to  line  up  in  columns. 

Ok 

10  PRINT  1  'NAME ! '  TAB  ;  25'    ; 'AMHUN  T  1 1   ;  PR\HT 

20  READ  Ab\3$ 

30  PR!  N  ■"  A$   TAB  i  25'  B$ 

-'i0  DATA  "L.    M.    JACOBS1'  .  "$25  .  £0  ' 1 

RUN 

NAME  AMfh:.Nf 

L.    M.    .J,"  COBS  j  9  2,  23 

Ok 
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TAN 
Function 


Purpose:     Returns  the  trigonometric  tangent  of  x. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 

Format:      v  =  TAN(.r) 


Remarks:   x  is  the  angle  in  radians.  To  convert  degrees 

to  radians,  multiply  by  PI/180,  where 
PI=3. 141593. 

TAN(x)   is  calculated  in  single  precision. 


Example:  Ok 

10  P  I -3-  1''*  1  59  3 
2  0  DEGREES-^ 5 

30   PRINT  TAN  I  DEGREES  '■■  P  I  /  1  80  ) 
RUN 
1 

Ok 

This  example  calculates  the  tangent  of  45  degrees. 


4-280 


TIME$ 

Variable  and  Statement 


Purpose:     Sets  or  retrieves  the  current  time. 

Versions:    Cassette     Disk      Advanced  Compiler 

#**  ***  *** 

Format:     As  a  variable: 

v$  =  TIME$ 
As  a  statement: 
TIMES  =  x$ 

Remarks:   For  the  variable  (v$  =  TIME$): 

The  current  time  is  returned  as  an  8  character  string. 
The  string  is  of  the  form  hh:mm:ss,  where  hh  is  the 
hour  (00  to  23),  mm  is  the  minutes  (00  to  59),  andx?  is 
the  seconds  (00  to  59).  The  time  may  have  been  set 
by  DOS  prior  to  entering  BASIC. 

For  the  statement  (TIME$  =  x$): 

The  current  time  is  set.  x$  is  a  string  expression 
indicating  the  time  to  be  set.  x$  may  be  given  in  one 
of  the  following  forms: 

hh  Set  the  hour  in  the  range  0  to  2  3.  Minutes 

and  seconds  default  to  00. 

hh:mm      Set  the  hour  and  minutes.  Minutes  must  be 
in  the  range  0  to  59.  Seconds  default  to  00. 

hh:mm:ss  Set  the  hour,  minutes,  and  seconds. 

Seconds  must  be  in  the  range  0  to  59. 
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TIME$ 

Variable  and  Statement 


A  leading  zero  may  be  omitted  from  any  of  the 
above  values,  but  you  must  include  at  least  one  digit. 
For  example,  if  you  wanted  to  set  the  time  as  a  half 
hour  after  midnight,  you  could  enter 
TIME$="0:30",  but  not  TIME$=":30".  If  any  of  the 
values  are  out  of  range,  an  "Illegal  function  call" 
error  is  issued.  The  previous  time  is  retained.  \ix$  is 
not  a  valid  string,  a  "Type  mismatch"  error  results. 


Example:   The  following  program  displays  the  time 
continuously  in  the  middle  of  the  screen. 

10  CLS 

2.0  LOCATE  10,15 

30  PRINT   T  I  f-4  E  $ 

'4  0  GOTO  30 
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TRON  and  TROFF 
Commands 


Purpose:     Traces  the  execution  of  program  statements. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  (**) 

Format:  TRON 
TROFF 


Remarks:  As  an  aid  in  debugging,  the  TRON  command  (which 
may  be  entered  in  indirect  mode)  enables  a  trace  flag 
that  prints  each  line  number  of  the  program  as  it  is 
executed.  The  numbers  appear  enclosed  in  square 
brackets.  The  trace  is  turned  off  by  the  TROFF 
command. 


Example: 


Ok 

10  !<-|0 

20  FOR  J=1   TO  2 

30  L-K   -4  10 

3  0  P  f<  !  f-  T   J  ;  K  ;  L 

30  K----K-f  !  0 

6  0  N  E  X  T 

70  E  u  r 


lOk 

i  0     2  0 

30 

30  t 

10  20 

30  60 

30 

2 

2  0  30 

:;0  60 

/  0 

0 1-. 

r  p  n  r  r 

p  i 

This  example  uses  TRON  and  TROFF  to  trace 
execution  of  a  loop.  The  numbers  in  brackets  are 
line  numbers;  the  numbers  not  in  brackets  at  the 
end  of  each  line  are  the  values  of  J,  K,  and  L  which 
are  printed  by  the  program. 
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USR 

Function 


Purpose:     Calls  the  indicated  machine  language  subroutine 
with  the  argument  arg. 


Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  (**) 


Format:      v=  USR[n](arg) 


Remarks:   n      is  in  the  range  0  to  9  and  corresponds  to  the 
digit  supplied  with  the  DEF  USR  statement  for 
the  desired  routine  (see  "DEF  USR  Statement" 
in  this  chapter).  If  n  is  omitted,  USRO  is 
assumed. 

arg    is  any  numeric  expression  or  string  variable, 
which  will  be  the  argument  to  the  machine 
language  subroutine. 

The  CALL  statement  is  another  way  to  call  a 
machine  language  subroutine.  See  "Appendix  C. 
Machine  Language  Subroutines"  for  complete 
information  on  using  machine  language 
subroutines. 


Example: 


50 
60 


DEF 
C  - 
D  = 


USR0  =  &HF 

USR0(B/2) 

USR(B/3) 


The  function  USRO  is  defined  in  line  10.  Line  50 
calls  the  function  USRO  with  the  argument  B/2.  Line 
60  calls  USRO  again,  with  the  argument  B/3. 
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VAL 
Function 


Purpose:     Returns  the  numerical  value  of  string  x$. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  *** 


Format:      v  =  VAL(x$) 

Remarks:  x$     is  a  string  expression. 

The  VAL  function  strips  blanks,  tabs,  and  line  feeds 
from  the  argument  string  in  order  to  determine  the 
result.  For  example, 

VAL("  -3") 

returns  -3. 

If  the  first  characters  of  x$  are  not  numeric,  then 
VAL(x$)  will  return  0  (zero). 

See  the  STR$  function  for  numeric  to  string 
conversion. 


Example:  ok 

PRINT  IML("'3^08  SHERWOOD  BLVD.") 

3^08 
Ok 

In  this  example,  VAL  is  used  to  extract  the  house 
number  from  an  address. 
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VARPTR 
Function 


Purpose:     Returns  the  address  in  memory  of  the  variable  or  file 
control  block. 


Versions:    Cassette     Disk      Advanced  Compiler 
***  ***  ***  **% 


Format:     v  =  VAKPTR(variable) 
v  =  VARPTR(#///^w) 


Remarks:   variable    is  the  name  of  a  numeric  or  string  variable 
or  array  element  in  your  program.  A  value 
must  be  assigned  to  variable  prior  to  the 
call  to  VARPTR,  or  an  "Illegal  function 
call"  error  results. 

filenum     is  the  number  under  which  the  file  was 
opened. 

For  both  formats,  the  address  returned  is  an  integer 
in  the  range  0  to  655  35.  This  number  is  the  offset 
into  BASIC'S  Data  Segment.  The  address  is  not 
affected  by  the  DEF  SEG  statement. 

The  first  format  returns  the  address  of  the  first  byte 
of  data  identified  with  variable.  The  format  of  this 
data  is  described  in  Appendix  I  under  "How 
Variables  Are  Stored." 

Note:    All  simple  variables  should  be  assigned 
before  calling  VARPTR  for  an  array,  because 
addresses  of  arrays  change  whenever  a  new 
simple  variable  is  assigned. 

VARPTR  is  usually  used  to  obtain  the  address  of  a 
variable  or  array  so  it  may  be  passed  to  a  USR 
machine  language  subroutine.  A  function  call  of  the 
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VARPTR 
Function 


form  VARPTR(A(0))  is  usually  specified  when 
passing  an  array,  so  that  the  lowest-addressed 
element  of  the  array  is  returned. 

The  second  format  returns  the  starting  address  of 
the  file  control  block  for  the  specified  file.  This  is 
not  the  same  as  the  DOS  file  control  block.  Refer  to 
"BASIC  File  Control  Block"  in  "Appendix  I. 

block. 

VARPTR  is  meaningless  for  cassette  files. 


Example:    This  example  reads  the  first  byte  in  the  buffer  of  a 
random  file: 

10  OPEN   "DATA.  F  I  L"  AS  1 
20  get  ••••  1 

30   '<jet   address  of   control  block 

40  FEBADR  -  VARPTR  <  ■■  1  ) 

50    1  '  i  gure  d d d  r  e  s  s  o  f  data  b u  t"  f  e  r 

60  DAT ADR  -  FCBADR+ 1 88 

70    'cet   first   byte   in  data  buffer 

80  A     =   PEEK (DAT ADR) 


The  next  example  use  VARPTR  to  get  the  data  from 
a  variable.  In  line  30,  P  gets  the  address  of  the  data. 
Integer  data  is  stored  in  two  bytes,  with  the  less 
significant  byte  first.  The  actual  value  stored  at 
location  P  is  calculated  in  line  40.  The  bytes  are  read 
with  the  PEEK  function,  and  the  second  byte  is 
multiplied  by  256  because  it  contains  the  high-order 
bits. 


10   DEFINT  A-Z 

20  DATA  1=500 

30  P=VARPTR(DATA1 ) 

k$  V  =  D E E K ( P )   +  256 'PEEK ( P+ 1 ) 

50  PRINT  V 
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VARPTR$ 
Function 


Purpose:     Returns  a  character  form  of  the  address  of  a  variable 
in  memory.  It  is  primarily  for  use  with  PLAY  and 
DRAW  in  programs  that  will  later  be  compiled. 

Versions:    Cassette      Disk      Advanced  Compiler 

*  *  *  *  *  *  *  *  * 


Format:      v$  =  VAKPTR$(variab/e) 

Remarks:   variable    is  the  name  of  a  variable  existing  in  the 
program. 

Note:  All  simple  variables  should  be  assigned 
before  calling  VARPTR$  for  an  array  element, 
because  addresses  of  arrays  change  whenever  a 
new  simple  variable  is  assigned. 


VARPTR$  returns  a  three-byte  string  in  the  form: 


Byte  0 

Byte  1 

Byte  2 

type 

low  byte  of 

variable 

address 

high  byte  of 

variable 

address 

type  indicates  the  variable  type: 

2  integer 

3  string 

4  single-precision 
8  double-precision 
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VARPTR$ 
Function 


The  returned  value  is  the  same  as: 

CHR$(/y^)+MKI$(VARPTR(wr/^/e)) 

You  can  use  VARPTR$  to  indicate  a  variable  name 
in  the  command  string  for  PLAY  or  DRAW.  For 
example: 

Method  One        Alternative  Method 

PLAY   "XA$;M  PLAY   "X"+VARPTR$ (A$ ) 

P LAY  "0=1  PLAY  "0="+VARPTR$ ( I ) 

This  technique  is  mainly  for  use  in  programs  which 
will  later  be  compiled. 


C/5 

H 

> 

m 
S 

2 
-J 


4-289 


WAIT 
Statement 


Purpose:     Suspends  program  execution  while  monitoring  the 
status  of  a  machine  input  port. 


Versions:  Cassette 
*** 


Disk 
*** 


Advanced 
*** 


Compiler 


Format:     WATT  port,  n[,m] 


Remarks:  port 


n,  m 


is  the  port  number,  in  the  range  0  to 
65535. 

are  integer  expressions  in  the  range  0  to 
255. 


Refer  to  the  IBM  Persona/  Computer  Technical  Reference 
manual  for  a  description  of  valid  port  numbers  (I/O 
addresses). 

The  WAIT  statement  causes  execution  to  be 
suspended  until  a  specified  machine  input  port 
develops  a  specified  bit  pattern. 

The  data  read  at  the  port  is  XORed  with  the  integer 
expression  m  and  then  ANDed  with  n.  If  the  result  is 
zero,  BASIC  loops  back  and  reads  the  data  at  the 
port  again.  If  the  result  is  nonzero,  execution 
continues  with  the  next  statement.  If  m  is  omitted,  it 
is  assumed  to  be  zero. 
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WAIT 
Statement 


The  WAIT  statement  lets  you  test  one  or  more  bit 
positions  on  an  input  port.  You  can  test  the  bit 
position  for  either  a  1  or  a  0.  The  bit  positions  to  be 
tested  are  specified  by  setting  l's  in  those  positions 

r.  -Uw  ,it,  ix  i  ill  d.liy  mi 

position  in  m  (for  which  there  is  a  1  bit  in  n)  causes 
WAIT  to  test  for  a  0  for  that  input  bit. 

When  executed,  the  WAIT  statement  loops  testing 
those  input  bits  specified  by  l's  in  n.  If  any  one  of 
those  bits  is  1  (orO  if  the  corresponding  bit  in  m  is  1), 
then  the  program  continues  with  the  next 
statement.  Thus  WAIT  does  not  wait  for  an  entire 
pattern  of  bits  to  appear,  but  only  for  one  of  them  to 
occur. 


Note:    It  is  possible  to  enter  an  infinite  loop 
with  the  WAIT  statement.  You  can  do  a 
Ctrl-Break  or  a  System  Reset  to  exit  the  loop. 


Example:   To  suspend  program  execution  until  port  32 
receives  a  1  bit  in  the  second  bit  position: 


100  MIT  32,2 
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WHILE  and  WEND 
Statements 


Purpose:     Executes  a  series  of  statements  in  a  loop  as  long  as  a 
given  condition  is  true. 

Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  *** 


Format:      WHILE  expression 


(loop  statements) 


WEND 


Remarks:   expression  is  any  numeric  expression. 

If  expression  is  true  (not  zero),  loop  statements  are 
executed  until  the  WEND  statement  is  encountered. 
BASIC  then  returns  to  the  WHILE  statement  and 
checks  expression.  If  it  is  still  true,  the  process  is 
repeated.  If  it  is  not  true,  execution  resumes  with 
the  statement  following  the  WEND  statement. 

WHILE.. .WEND  loops  may  be  nested  to  any  level. 
Each  WEND  will  match  the  most  recent  WHILE. 
An  unmatched  WHILE  statement  causes  a  "WHILE 
without  WEND"  error,  and  an  unmatched  WEND 
statement  causes  a  "WEND  without  WHILE"  error. 
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WHILE  and  WEND 
Statements 


Example:   This  example  sorts  the  elements  of  the  string  array 
A$  into  alphabetical  order.  A$  was  defined  with  J 
elements. 

90    'bubble  sort  array  A$ 

100  F  L  I  P  5  = 1    'force  one  pass   thru  loop 

110  WH 1 LE  FL I  PS 

113  FLIPS=0 

120     FOR   1=1   TO  J-1 

1  30       IF  A  $ ( I )   A$ ( 1  +  1)  THEN 

SWAP  A$ ( I ) ,A$ ( 1+1 >  :    FLI PS= 1 
1*+0     NEXT  I 
150  WEND 


> 

m 

tn 
Z 
H 

C/5 
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WIDTH 
Statement 


Purpose:     Sets  the  output  line  width  in  number  of  characters. 
After  outputting  the  indicated  number  of 
characters,  BASIC  adds  a  carriage  return. 


Versions:    Cassette      Disk      Advanced  Compiler 
***  ***  ***  (**) 


Format:      WIDTH  size 

WIDTH  filenum,  size 
WIDTH  device,  size 


Remarks:  size  is  a  numeric  expression  in  the  range  0  to 

255.  This  is  the  new  width.  WIDTH  0  is 
the  same  thing  as  WIDTH  1. 

filenum  is  a  numeric  expression  in  the  range  1  to 
15.  This  is  the  number  of  a  file  opened  to 
one  of  the  devices  listed  below. 


device  is  a  string  expression  for  the  device 
identifier.  Valid  devices  are  SCRN:, 
LPT1:,  LPT2:,  LPT3:,  COMl:,  or  COM2:. 


Depending  upon  the  device  specified,  the  following 
actions  are  possible: 

WIDTH  size  or  WIDTH  "SCRN:", size 

Sets  the  screen  width.  Only  40  or  80 
column  width  is  allowed. 


If  the  screen  is  in  medium  resolution 
graphics  mode  (as  would  occur  with  a 
SCREEN  1  statement),  WIDTH  80  forces 
the  screen  into  high  resolution  (just  like  a 
SCREEN  2  statement). 
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WIDTH 
Statement 


If  the  screen  is  in  high  resolution  graphics 
mode  (as  would  occur  with  a  SCREEN  2 
statement),  WIDTH  40  forces  the  screen 
into  medium  resolution  (like  a  SCREEN  1 
statement). 


Note:    Changing  the  screen  width 
causes  the  screen  to  be  cleared,  and 
sets  the  border  screen  color  to  black. 


WIDTH  device, size 

Used  as  a  deferred  width  assignment  for 
the  device.  This  form  of  width  stores  the 
new  width  value  without  actually  changing 
the  current  width  setting.  A  subsequent 
OPEN  to  the  device  will  use  this  value  for 
width  while  the  file  is  open.  The  width 
does  not  change  immediately  if  the  device 
is  already  open. 

Note:    LPRINT,  LLIST,  and 
LIST,"LPTn:"  do  an  implicit  OPEN 
and  are  therefore  affected  by  this 
statement. 

WIDTH  Jilenunusize 

The  width  of  the  device  associated  with 
filenum  is  immediately  changed  to  the  new 
size  specified.  This  allows  the  width  to  be 
changed  at  will  while  the  file  is  open.  This 
form  of  WIDTH  has  meaning  only  for 
LPTl:  in  Cassette  BASIC.  Disk  and 
Advanced  BASIC  also  allow  LPT2:,  LPT3:, 
COM1:  and  COM2:. 
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WIDTH 
Statement 


Any  value  entered  outside  of  the  ranges  indicated 
will  result  in  an  "Illegal  function  call"  error.  The 
previous  value  is  retained. 

WIDTH  has  no  effect  for  the  keyboard  (KYBD:)  or 
cassette  (CASl:). 

The  width  for  each  printer  defaults  to  80  when 
BASIC  is  started.  The  maximum  width  for  the  IBM 
80  CPS  Matrix  Printer  is  132.  However,  no  error  is 
returned  for  values  between  132  and  25  5. 

It  is  up  to  you  to  set  the  appropriate  physical  width 
on  your  printer.  Some  printers  are  set  by  sending 
special  codes,  some  have  switches.  For  the  IBM  80 
CPS  Matrix  Printer  you  should  use  LPRINT 
CHR$(1 5);  to  change  to  a  condensed  typestyle  when 
printing  at  widths  greater  than  80.  Use  LPRINT 
CHR$(18);  to  return  to  normal.  The  IBM  80  CPS 
Matrix  Printer  is  set  up  to  automatically  add  a 
carriage  return  if  you  exceed  the  maximum  line 
length. 

Specifying  a  width  of  255  disables  line  folding.  This 
has  the  effect  of  "infinite"  width.  WIDTH  255  is  the 
default  for  communications  files. 

Changing  the  width  for  a  communications  file  does 
not  alter  either  the  receive  or  the  transmit  buffer;  it 
just  causes  BASIC  to  send  a  carriage  return 
character  after  every  size  characters. 

Changing  screen  mode  affects  screen  width  only 
when  moving  between  SCREEN  2  and  SCREEN  1  or 
SCREEN  0.  See  "SCREEN  Statement"  in  this 
chapter. 
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WIDTH 
Statement 


Example:    10  WIDTH  "LPT  1  :  "  ,  75 

20  OPEN  "LPT1:"  FOR  OUTPUT  AS  1 


602  0  W  I  DTH     1  ,  40 


In  the  preceding  example,  line  10  stores  a  printer 
width  of  75  characters  per  line.  Line  20  opens  file  #1 
to  the  printer  and  sets  the  width  to  75  for 
subsequent  PRINT  #1,...  statements.  Line  6020 
changes  the  current  printer  width  to  40  characters 
per  line. 


SCREEN   1,0     'Set    to  meci-res   color  graphics 
WIDTH  80         'Go   to  hi -res  graphics 
WIDTH  40         'Go  back  to  riedium  res 


SCREEN  0,1  'Go  to  40x25  text  color  (node 
WIDTH  80         'Go  to  80x25  text:  color  mode 


> 

m 

w 
25 

<z> 
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WRITE 
Statement 


Purpose:     Outputs  data  on  the  screen. 

Versions:    Cassette      Disk      Advanced  Compiler 


sfc  sfe  sfe  :{c  sfe  $ 


Format:      WRITE  [list  of  expressions] 


Remarks:   list  of  expressions 

is  a  list  of  numeric  and/or  string 
expressions,  separated  by  commas  or 
semicolons. 


If  the  list  of  expressions  is  omitted,  a  blank  line  is 
output.  If  the  list  of  expressions  is  included,  the 
values  of  the  expressions  are  output  on  the  screen. 


When  the  values  of  the  expressions  are  output,  each 
item  is  separated  from  the  last  by  a  comma.  Strings 
are  delimited  by  quotation  marks.  After  the  last  item 
in  the  list  is  printed,  BASIC  adds  a  carriage 
return/line  feed. 


WRITE  is  similar  to  PRINT.  The  difference 
between  WRITE  and  PRINT  is  that  WRITE  inserts 
commas  between  the  items  as  they  are  displayed  and 
delimits  strings  with  quotation  marks.  Also,  positive 
numbers  are  not  preceded  by  blanks. 


Example:    This  example  shows  how  WRITE  displays  numeric 
and  string  values. 

10  A=80:    B-90:    C$  =  ''THAT'S  ALL11 

20  WRITE  A,B,C$ 

RUN 

80  ,90  ,  "THAT  1  S  ALL1 
Ok 
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WRITE  # 
Statement 


Purpose:     Writes  data  to  a  sequential  file. 


Versions:    Cassette     Disk      Advanced  Compiler 


Format:      WRITE  ffilenum,  list  of  expressions 


Remarks:  filenum 


is  the  number  under  which  the  file  was 
opened  for  output. 


list  of  expressions 

is  a  list  of  string  and/or  numeric 
expressions,  separated  by  commas  or 
semicolons. 

The  difference  between  WRITE  #  and  PRINT  #  is 
that  WRITE  #  inserts  commas  between  the  items  as 
they  are  written  and  delimits  strings  with  quotation 
marks.  Therefore,  it  is  not  necessary  for  the  user  to 
put  explicit  delimiters  in  the  list.  Also,  WRITE  # 
does  not  put  a  blank  in  front  of  a  positive  number.  A 
carriage  return/line  feed  sequence  is  inserted  after 
the  last  item  in  the  list  is  written. 
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WRITE  # 
Statement 

Example:   Let  A$="CAMERA"  and  B$="93604-l".  The 
statement: 

WRITE  --1  ,A$,B$ 

writes  the  following  image  to  the  file. 

"CAMERA","93604-1" 
A  subsequent  INPUT  #  statement,  such  as: 

I  N  PUT     \  ,  A  $  ,  B  !? 

would  input  "CAMERA"  to  A$  and  "93604-1"  to 
B$. 
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endix  A.  Messages 


If  BASIC  detects  an  error  that  causes  a  program  to 
stop  running,  an  error  message  is  displayed.  It  is 
possible  to  trap  and  test  errors  in  a  BASIC  program 
using  the  ON  ERROR  statement  and  the  ERR  and 
ERL  variables.  (For  complete  explanations  of  ON 
ERROR,  ERR  and  ERL,  see  "Chapter  4.  BASIC 
Commands,  Statements,  Functions,  and  Variables.") 

This  appendix  lists  all  the  BASIC  error  messages 
with  their  associated  error  numbers. 

Number  Message 

1       NEXT  without  FOR 

The  NEXT  statement  doesn't  have  a 
corresponding  FOR  statement.  It  may  be 
that  a  variable  in  the  NEXT  statement 
does  not  correspond  to  any  previously 
executed  and  unmatched  FOR  statement 
variable. 


A  line  contains  an  incorrect  sequence  of 
characters,  such  as  an  unmatched 
parenthesis,  a  misspelled  command  or 
statement,  or  incorrect  punctuation.  Or, 
the  data  in  a  DATA  statement  doesn't 
match  the  type  (numeric  or  string)  of  the 
variable  in  a  READ  statement. 

When  this  error  occurs,  the  BASIC 
program  editor  automatically  displays  the 
line  in  error.  Correct  the  line  or  the 
program. 


Fix  the  program  so  the  NEXT  has  a 
matching  FOR. 


2 


Syntax  error 
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3  RETURN  without  GOSUB 

A  RETURN  statement  needs  a  previous 
unmatched  GOSUB  statement. 

Correct  the  program.  You  probably  need 
to  put  a  STOP  or  END  statement  before 
the  subroutine  so  the  program  doesn't 
"fall"  into  the  subroutine  code. 

4  Out  of  data 

A  READ  statement  is  trying  to  read  more 
data  than  is  in  the  DATA  statements. 

Correct  the  program  so  that  there  are 
enough  constants  in  the  DATA  statements 
for  all  the  READ  statements  in  the 
program. 

5  Illegal  function  call 

A  parameter  that  is  out  of  range  is  passed 
to  a  system  function.  The  error  may  also 
occur  as  the  result  of: 

•  A  negative  or  unreasonably  large 
subscript 

•  Trying  to  raise  a  negative  number  to  a 
power  that  is  not  an  integer 

•  Calling  a  USR  function  before 
defining  the  starting  address  with 
DEF  USR 

•  A  negative  record  number  on  GET  or 
PUT  (file) 

•  An  improper  argument  to  a  function 
or  statement 

•  Trying  to  list  or  edit  a  protected 
BASIC  program 

•  Trying  to  delete  line  numbers  which 
don't  exist 
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Number  Message 


Correct  the  program.  Refer  to  "Chapter 
4.  Basic  Commands,  Statements, 
Functions,  and  Variables"  for  information 
about  the  particular  statement  or 
function. 

6  Overflow 

The  magnitude  of  a  number  is  too  large  to 
be  represented  in  BASIC'S  number  format. 
Integer  overflow  will  cause  execution  to 
stop.  Otherwise,  machine  infinity  with  the 
appropriate  sign  is  supplied  as  the  result 
and  execution  continues. 

To  correct  integer  overflow,  you  need  to 
use  smaller  numbers,  or  change  to  single- 
or  double-precision  variables. 

Note:    If  a  number  is  too  small  to  be 
represented  in  BASIC'S  number  format, 
we  have  an  underflow  condition.  If  this 
occurs,  the  result  is  zero  and  execution 
continues  without  an  error. 

7  Out  of  memory 

A  program  is  too  large,  has  too  many  FOR 
loops  or  GOSUBs,  too  many  variables, 
expressions  that  are  too  complicated,  or 
complex  painting. 

You  may  want  to  use  CLEAR  at  the 
beginning  of  your  program  to  set  aside 
more  stack  space  or  memory  area. 

8  Undefined  line  number 

A  line  reference  in  a  statement  or 
command  refers  to  a  line  which  doesn't 
exist  in  the  program. 

Check  the  line  numbers  in  your  program, 
and  use  the  correct  line  number. 
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9        Subscript  out  of  range 

You  used  an  array  element  either  with  a 
subscript  that  is  outside  the  dimensions  of 
the  array,  or  with  the  wrong  number  of 
subscripts. 

Check  the  usage  of  the  array  variable.  You 
may  have  put  a  subscript  on  a  variable  that 
is  not  an  array,  or  you  may  have  coded  a 
built-in  function  incorrectly. 

10  Duplicate  Definition 

You  tried  to  define  the  size  of  the  same 
array  twice.  This  may  happen  in  one  of 
several  ways: 

•  The  same  array  is  defined  in  two  DIM 
statements. 

•  The  program  encounters  a  DIM 
statement  for  an  array  after  the 
default  dimension  of  10  is  established 
for  that  array. 

•  The  program  sees  an  OPTION  BASE 
statement  after  an  array  has  been 
dimensioned,  either  by  a  DIM 
statement  or  by  default. 

Move  the  OPTION  BASE  statement  to 
make  sure  it  is  executed  before  you  use 
any  arrays;  or,  fix  the  program  so  each 
array  is  defined  only  once. 

11  Division  by  zero 

In  an  expression,  you  tried  to  divide  by 
zero,  or  you  tried  to  raise  zero  to  a  negative 
power. 

It  is  not  necessary  to  fix  this  condition, 
because  the  program  continues  running. 
Machine  infinity  with  the  sign  of  the 
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Number 


Message 


number  being  divided  is  the  result  of  the 
division;  or,  positive  machine  infinity  is 
the  result  of  the  exponentiation. 

You  tried  to  enter  a  statement  in  direct 
mode  which  is  invalid  in  direct  mode  (such 
as  DEF  FN). 

The  statement  should  be  entered  as  part  of 
a  program  line. 

13  Type  mismatch 

You  gave  a  string  value  where  a  numeric 
value  was  expected,  or  you  had  a  numeric 
value  in  place  of  a  string  value.  This  error 
may  also  be  caused  by  trying  to  SWAP 
variables  of  different  types,  such  as 
single-  and  double-precision. 

14  Out  of  string  space 

BASIC  allocates  string  space  dynamically 
until  it  runs  out  of  memory.  This  message 
means  that  string  variables  caused  BASIC 
to  exceed  the  amount  of  free  memory 
remaining  after  housecleaning. 

15  String  too  long 

You  tried  to  create  a  string  more  than  255 
characters  long. 

Try  to  break  the  string  into  smaller  strings. 

16  String  formula  too  complex 

A  string  expression  is  too  long  or  too 
complex. 

The  expression  should  be  broken  into 
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17  Can't  continue 

You  tried  to  use  CONT  to  continue  a 
program  that: 

•  Halted  due  to  an  error, 

•  Was  modified  during  a  break  in 
execution,  or 

•  Does  not  exist 

Make  sure  the  program  is  loaded,  and  use 
RUN  to  run  it. 

18  Undefined  user  function 

You  called  a  function  before  defining  it 
with  the  DEF  FN  statement. 

Make  sure  the  program  executes  the  DEF 
FN  statement  before  you  use  the  function. 

19  No  RESUME 

The  program  branched  to  an  active  error 
trapping  routine  as  a  result  of  an  error 
condition  or  an  ERROR  statement.  The 
routine  does  not  have  a  RESUME 
statement.  (The  physical  end  of  the 
program  was  encountered  in  the  error 
trapping  routine.) 

Be  sure  to  include  RESUME  in  your  error 
trapping  routine  to  continue  program 
execution.  You  may  want  to  add  an  ON 
ERROR  GOTO  0  statement  to  your  error 
trapping  routine  so  BASIC  displays  the 
message  for  any  untrapped  error. 

20  RESUME  without  error 

The  program  has  encountered  a  RESUME 
statement  without  having  trapped  an 
error.  The  error  trapping  routine  should 
only  be  entered  when  an  error  occurs  or  an 
ERROR  statement  is  executed. 
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You  probably  need  to  include  a  STOP  or 
END  statement  before  the  error  trapping 
routine  to  prevent  the  program  from 
"falling  into"  the  error  trapping  code. 

22  Missing  operand 

An  expression  contains  an  operator,  such 
as  *  or  OR,  with  no  operand  following  it. 

Make  sure  you  include  all  the  required 
operands  in  the  expression. 

23  Line  buffer  overflow 

You  tried  to  enter  a  line  that  has  too  many 
characters. 


Separate  multiple  statements  on  the  line 
so  they  are  on  more  than  one  line.  You 
might  also  use  string  variables  instead  of 
constants  where  possible. 

24     Device  Timeout 

BASIC  did  not  receive  information  from 
an  input/output  device  within  a 
predetermined  amount  of  time.  In 
Cassette  BASIC,  this  only  occurs  while  the 
program  is  trying  to  read  from  the  cassette 
or  write  to  the  printer. 

For  communications  files,  this  message 
indicates  that  one  or  more  of  the  signals 
tested  with  OPEN  "COM...  was  not  found 
in  the  specified  period  of  time. 


Retry  the  operation. 


25      Device  Fault 

A  hardware  error  indication  was  returned 
by  an  interface  adapter. 

In  Cassette  BASIC,  this  only  occurs  when  a 
fault  status  is  returned  from  the  printer 
interface  adapter. 
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25      This  message  may  also  occur  when 
(cont.)  transmitting  data  to  a  communications 
file.  In  this  case,  it  indicates  that  one  or 
more  of  the  signals  being  tested  (specified 
on  the  OPEN  "COM...  statement)  was  not 
found  in  the  specified  period  of  time. 

-i  /-        i:nu  — ;  4 1  MCVT 

matching  NEXT.  That  is,  a  FOR  loop  was 
active  when  the  physical  end  of  the 
program  was  reached. 

Correct  the  program  so  it  includes  a  NEXT 
statement. 

27      Out  of  Paper 

The  printer  is  out  of  paper,  or  the  printer  is 
not  switched  on. 

You  should  insert  paper  (if  necessary), 
verify  that  the  printer  is  properly 
connected,  and  make  sure  that  the  power 
is  on;  then,  continue  the  program. 

29  WHILE  without  WEND 

A  WHILE  statement  does  not  have  a 
matching  WEND.  That  is,  a  WHILE  was 
still  active  when  the  physical  end  of  the 
program  was  reached. 

Correct  the  program  so  that  each  WHILE 
has  a  corresponding  WEND. 

30  WEND  without  WHILE 

A  WEND  is  encountered  before  a 
matching  WHILE  was  executed. 

Correct  the  program  so  that  there  is  a 
WHILE  for  each  WEND. 
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50  FIELD  overflow 

A  FIELD  statement  is  attempting  to 
allocate  more  bytes  than  were  specified  for 
the  record  length  of  a  random  file  in  the 
OPEN  statement.  Or,  the  end  of  the 
FIELD  buffer  is  encountered  while  doing 
sequential  I/O  (PRINT  #,  WRITE  #, 
INPUT  #)  to  a  random  file. 

Check  the  OPEN  statement  and  the 
FIELD  statement  to  make  sure  they 
correspond.  If  you  are  doing  sequential 
I/O  to  a  random  file,  make  sure  that  the 
length  of  the  data  read  or  written  does  not 
exceed  the  record  length  of  the  random 
file. 

51  Internal  error 

An  internal  malfunction  occurred  in 
BASIC. 

Recopy  your  diskette.  Check  the  hardware 
and  retry  the  operation.  If  the  error 
reoccurs,  report  to  your  computer  dealer 
the  conditions  under  which  the  message 
appeared. 

52  Bad  file  number 

A  statement  uses  a  file  number  of  a  file  that 
is  not  open,  or  the  file  number  is  out  of  the 
range  of  possible  file  numbers  specified  at 
initialization.  Or,  the  device  name  in  the 
file  specification  is  too  long  or  invalid,  or 
the  filename  was  too  long  or  invalid. 

Make  sure  the  file  you  wanted  was  opened 
and  that  the  file  number  was  entered 
correctly  in  the  statement.  Check  that  you 
have  a  valid  file  specification  (refer  to 
"Naming  Files"  in  Chapter  3  for 
information  on  file  specifications). 
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File  not  found 

A  LOAD,  KILL,  NAME,  FILES,  or  OPEN 
references  a  file  that  does  not  exist  on  the 
diskette  in  the  specified  drive. 

Verify  that  the  correct  diskette  is  in  the 
drive  specified,  and  that  the  file 
specification  was  entered  correctly.  Then 
retry  the  operation. 

Bad  file  mode 

You  tried  to  use  PUT  or  GET  with  a 
sequential  file  or  a  closed  file;  or  to 
execute  an  OPEN  with  a  file  mode  other 
than  input,  output,  append,  or  random. 

Make  sure  the  OPEN  statement  was 
entered  and  executed  properly.  GET  and 
PUT  require  a  random  file. 

This  error  also  occurs  if  you  try  to  merge  a 
file  that  is  not  in  ASCII  format.  In  this  case, 
make  sure  you  are  merging  the  right  file.  If 
necessary,  load  the  program  and  save  it 
again  using  the  A  option. 

File  already  open 

You  tried  to  open  a  file  for  sequential 
output  or  append,  and  the  file  is  already 
opened;  or,  you  tried  to  use  KILL  on  a  file 
that  is  open. 

Make  sure  you  only  execute  one  OPEN  to 
a  file  if  you  are  writing  to  it  sequentially. 
Close  a  file  before  you  use  KILL. 

Device  I/O  Error 

An  error  occurred  on  a  device  I/O 
operation.  DOS  cannot  recover  from  the 
error. 


Number  Message 


When  receiving  communications  data, 
this  error  can  occur  from  overrun, 
framing,  break,  or  parity  errors.  When  you 
are  receiving  data  with  7  or  less  data  bits, 
the  eighth  bit  is  turned  on  in  the  byte  in 
error. 


58      File  already  exists 

The  filename  specified  in  a  NAME 
statement  matches  a  filename  already  in 
use  on  the  diskette. 

Retry  the  NAME  command  using  a 
different  name. 


61      Disk  full 

All  diskette  storage  space  is  in  use.  Files 
are  closed  when  this  error  occurs. 


If  there  are  any  files  on  the  diskette  that 
you  no  longer  need,  erase  them;  or,  use  a 
new  diskette.  Then  retry  the  operation  or 
rerun  the  program. 


62      Input  past  end 

This  is  an  end  of  file  error.  An  input 
statement  is  executed  for  a  null  (empty) 
file,  or  after  all  the  data  in  a  sequential  file 
was  already  input. 

To  avoid  this  error,  use  the  EOF  function 
to  detect  the  end  of  file. 


This  error  also  occurs  if  you  try  to  read 
from  a  file  that  was  opened  for  output  or 
append.  If  you  want  to  read  from  a 
sequential  output  (or  append)  file,  you 
must  close  it  and  open  it  again  for  input. 
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63  Bad  record  number 

In  a  PUT  or  GET  statement,  the  record 
number  is  either  greater  than  the 
maximum  allowed  (32767)  or  equal  to 
zero. 

Correct  the  PUT  or  GET  statement  to  use 
a  valid  record  number. 

64  Bad  file  name 

An  invalid  form  is  used  for  the  filename 
with  BLOAD,  BSAVE,  KILL,  NAME, 
OPEN,  or  FILES. 

Check  "Naming  Files"  in  Chapter  3  for 
information  on  valid  filenames,  and 
correct  the  filename  in  error. 

66  Direct  statement  in  file 

A  direct  statement  was  encountered  while 
loading  or  chaining  to  an  ASCII  format 
file.  The  LOAD  or  CHAIN  is  terminated. 

The  ASCII  file  should  consist  only  of 
statements  preceded  by  line  numbers. 
This  error  may  occur  because  of  a  line  feed 
character  in  the  input  stream.  Refer  to 
"Appendix  D.  Converting  Programs  to 
IBM  Personal  Computer  BASIC" 

67  Too  many  files 

An  attempt  is  made  to  create  a  new  file 
(using  SAVE  or  OPEN)  when  all  directory 
entries  on  the  diskette  are  full,  or  when  the 
file  specification  is  invalid. 

If  the  file  specification  is  okay,  use  a  new 
formatted  diskette  and  retry  the 
operation. 

68  Device  Unavailable 

You  tried  to  open  a  file  to  a  device  which 
doesn't  exist.  Either  you  do  not  have  the 
hardware  to  support  the  device  (such  as 
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printer  adapters  for  a  second  or  third 
printer),  or  you  have  disabled  the  device. 
(For  example,  you  may  have  used  /C:0  on 
the  BASIC  command  to  start  Disk  BASIC. 
That  would  disable  communications 
devices.) 

Make  sure  the  device  is  installed  correctly. 
If  necessary,  enter  the  command: 


SYSTEM 


This  returns  you  to  DOS  where  you  can 
re-enter  the  BASIC  command. 


69      Communication  buffer  overflow 

A  communication  input  statement  was 
executed,  but  the  input  buffer  was  already 
full. 


You  should  use  an  ON  ERROR  statement 
to  retry  the  input  when  this  condition 
occurs.  Subsequent  inputs  attempt  to 
clear  this  fault  unless  characters  continue 
to  be  received  faster  than  the  program  can 
process  them.  If  this  happens  there  are 
several  possible 


•  Increase  the  size  of  the 
communications  buffer  using  the  /C: 
option  when  you  start  BASIC. 

•  Implement  a  "hand-shaking"  protocol 
with  the  other  computer  to  tell  it  to 
stop  sending  long  enough  so  you  can 
catch  up.  (See  the  example  in 
"Appendix  F.  Communications.") 

•  Use  a  lower  baud  rate  to  transmit  and 
receive. 
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Number 
70 


71 


72 


73 
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Message 

Disk  Write  Protect 

You  tried  to  write  to  a  diskette  that  is 
write-protected. 

Make  sure  you  are  using  the  right  diskette. 
If  so,  remove  the  write  protection,  then 
retry  the  operation. 

This  error  may  also  occur  because  of  a 
hardware  failure. 

Disk  not  Ready 

The  diskette  drive  door  is  open  or  a 
diskette  is  not  in  the  drive. 

Place  the  correct  diskette  in  the  drive  and 
continue  the  program. 

Disk  Media  Error 

The  controller  attachment  card  detected  a 
hardware  or  media  fault.  Usually,  this 
means  that  the  diskette  has  gone  bad. 

Copy  any  existing  files  to  a  new  diskette 
and  re-format  the  bad  diskette.  If 
formatting  fails,  the  diskette  should  be 
discarded. 

Advanced  Feature 

Your  program  used  an  Advanced  BASIC 
feature  while  you  were  using  Disk  BASIC. 

Start  Advanced  BASIC  and  rerun  your 
program. 

Unprintable  error 

An  error  message  is  not  available  for  the 
error  condition  which  exists.  This  is 
usually  caused  by  an  ERROR  statement 
with  an  undefined  error  code. 

Check  your  program  to  make  sure  you 
handle  all  error  codes  which  you  create. 


endix  B.  BASIC  Diskette  Input 
and  Output 


This  appendix  describes  procedures  and  special 
considerations  for  using  diskette  input  and  output. 
It  contains  lists  of  the  commands  and  statements 
that  are  used  with  diskette  files,  and  explanations  of 
how  to  use  them.  Several  sample  programs  are 
included  to  help  clarify  the  use  of  data  files  on 
diskette.  If  you  are  new  to  BASIC  or  if  you're  getting 
diskette-related  errors,  read  through  these 
procedures  and  program  examples  to  make  sure 
you're  using  all  the  diskette  statements  correctly. 

You  may  also  want  to  refer  to  the  IBM  Personal 
Computer  Disk  Operating  System  manual  for  other 
information  on  handling  diskettes  and  diskette  files. 

Note:    Most  of  the  information  in  this 
appendix  about  program  files  and  sequential 
files  applies  to  cassette  I/O  as  well.  The  cassette 
cannot  be  opened  in  random  mode,  however. 
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Specifying  Filenames 


Filenames  for  diskette  files  must  conform  to  DOS 
naming  conventions  in  order  for  BASIC  to  be  able  to 
read  them.  Refer  to  "Naming  Files"  in  Chapter  3  to 
be  sure  you  are  specifying  your  diskette  files 
correctly. 


Commands  for  Program  Files 


The  commands  which  you  can  use  with  your  BASIC 
program  files  are  listed  below,  with  a  quick 
description.  For  more  detailed  information  on  any 
of  these  commands,  refer  to  "Chapter  4.  BASIC 
Commands,  Statements,  Functions,  and  Variables." 

SAVE  filespec  [,A] 

Writes  to  diskette  the  program  that  is 
currently  residing  in  memory.  Optional  A 
writes  the  program  as  a  series  of  ASCII 
characters.  (Otherwise,  BASIC  uses  a 
compressed  binary  format.) 

LOAD  filespec  [,R] 

Loads  the  program  from  diskette  into 
memory.  Optional  R  runs  the  program 
immediately.  LOAD  always  deletes  the 
current  contents  of  memory  and  closes  all 
files  before  loading.  If  R  is  included, 
however,  open  data  files  are  kept  open. 
Thus,  programs  can  be  chained  or  loaded 
in  sections,  and  can  access  the  same  data 
files. 
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RUN  filespec  [,R] 

RUN  filespec  loads  the  program  from 
diskette  into  memory  and  runs  it.  RUN 
deletes  the  current  contents  of  memory 
and  closes  all  files  before  loading  the 
program.  If  the  R  option  is  included, 
however,  all  open  data  files  are  kept  open. 

MERGE  filespec 

Loads  the  program  from  diskette  into 
memory,  but  does  not  delete  the  current 
contents  of  memory.  The  program  line 
numbers  on  diskette  are  merged  with  the 
line  numbers  in  memory.  If  two  lines  have 
the  same  number,  only  the  line  from  the 
diskette  program  is  saved.  After  a  MERGE 
command,  the  "merged"  program  resides 
in  memory,  and  BASIC  returns  to 
command  level. 

KILL  filespec 

Deletes  the  file  from  the  diskette. 

NAME  filespec  AS  filename 

Changes  the  name  of  a  diskette  file. 


Protected  Files 

If  you  wish  to  save  a  program  in  an  encoded  binary 
format,  use  the  P  (protect)  option  with  the  SAVE 
command.  For  example: 


A  program  saved  this  way  cannot  be  listed,  saved,  or 
edited.  Since  you  cannot  "unprotect"  such  a 
program,  you  may  also  want  to  save  an  unprotected 
copy  of  the  program  for  listing  and  editing 
purposes. 
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Diskette  Data  Files  -  Sequential  and 
Random  I/O 


Two  types  of  diskette  data  files  may  be  created  and 
accessed  by  a  BASIC  program:  sequential  files  and 
random  access  files. 


Sequential  files  are  easier  to  create  than  random  files 
but  are  limited  in  flexibility  and  speed  when  it 
comes  to  accessing  the  data.  The  data  that  is  written 
to  a  sequential  file  is  stored  sequentially,  one  item 
after  another,  in  the  order  that  each  item  is  sent. 
Each  item  is  read  back  in  the  same  way,  from  the 
first  item  in  the  file,  to  the  last  item. 

The  statements  and  functions  that  are  used  with 
sequential  files  are: 


PRINT  #  USING 

Creating  and  Accessing  a  Sequential  File 

To  create  a  sequential  file  and  access  the  data  in  the 
file,  include  the  following  steps  in  your  program: 

1.     Open  the  file  for  output  or  append  using  the 
OPEN  statement. 


2.     Write  data  to  the  file  using  the  PRINT  #, 
WRITE  #,  or  PRINT  #  USING  statements. 


Sequential  Files 


CLOSE 
INPUT  # 
LINE  INPUT  # 
OPEN 
PRINT  # 


WRITE  # 

EOF 

INPUTS 


LOC 
LOF 
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3.  To  access  the  data  in  the  file,  you  must  close  the 
file  (using  CLOSE)  and  reopen  it  for  input 
(using  OPEN). 

4.  Use  the  INPUT  #  or  LINE  INPUT  #  statements 
to  read  data  from  the  sequential  file  into  the 
program. 

The  following  are  example  program  lines  that 
demonstrate  these  steps. 


The  above  program  could  also  have  been  written  as 
follows: 


Notice  that  both  ways  of  writing  the  OPEN 
statement  yield  the  same  results.  Look  under 
"OPEN  Statement"  in  Chapter  4  for  details  of  the 
syntax  of  each  form  of  OPEN. 

The  following  program,  PROGRAMl,  is  a  short 
program  that  creates  a  sequential  file,  "DATA", 
from  information  you  enter  at  the  keyboard. 
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Program  1 


1  REM  PR0GRAM1   -  create  a  sequential  file 

10  OPEN  "DATA"  FOR  OUTPUT  AS  -1 

20    INPUT  "NAME";N$ 

25   IF  NS="DONE"  THEN  CLOSE:  END 

30   INPUT  "DEPARTMENT" ; D$ 

40   INPUT  "DATE  HI  RED" ; H$ 

50  WRITE  -1,N$,D$,H$ 

60  PRINT:   GOTO  20 

RUN 

NAME?  MICHELANGELO 
DEPARTMENT?  AUDIO/VISUAL  AIDS 
DATE  HIRED?  01/12/72 


NAME?  SHERLOCK  HOLMES 
DEPARTMENT?  RESEARCH 
DATE  HIRED?  12/03/65 

NAME?  EBENEEZER  SCROOGE 
DEPARTMENT?  ACCOUNTING 
DATE  HIRED?  04/27/78 


NAME?  SUPER  MANN 
DEPARTMENT?  MAINTENANCE 
DATE  HIRED?  08/16/78 

NAME?  DONE 
Ok 


Now  look  at  PROGRAM2.  It  accesses  the  file 
"DATA"  that  was  created  in  PROGRAMl  and 
displays  the  name  of  everyone  hired  in  1978. 

Program  2 

1   REM  PR0GRAM2  -  accessing  a  sequential  file 
10  OPEN  "DATA"  FOR   INPUT  AS  1 
20   INPUT  #) ,N$,D$,H$ 

30   IF  RIGHT$(H$,2)=1'78"  THEN  PRINT  N$ 

40  GOTO  20 

RUN 

EBENEEZER  SCROOGE 
SUPER  MANN 

Input  past  end  in  20 
Ok 
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PROGRAM2  reads,  sequentially,  every  item  in  the 
file.  When  all  the  data  has  been  read,  line  20  causes 
an  "Input  past  end"  error.  To  avoid  getting  this 
error,  insert  line  15  which  uses  the  EOF  function  to 
test  for  end  of  file: 

15    IF   ECFi'l.)    THEN   CLOSE.  :  END 

and  change  line  40  to  GOTO  15.  The  end  of  file  is 
indicated  by  a  special  character  in  the  file.  This 
character  has  ASCII  code  26  (hex  lA).  Therefore, 
you  should  not  put  a  CHR$(26)  in  a  sequential  file. 

A  program  that  creates  a  sequential  file  can  also 
write  formatted  data  to  the  diskette  with  the 
PRINT  #  USING  statement.  For  example,  the 
statement: 

PRINT  -•  1  ,  US  I  N G  "  .  •■■  '  , 1  ;  A,  B  ,  C  ,  D 

could  be  used  to  write  numeric  data  to  diskette 
without  explicit  delimiters.  The  comma  at  the  end 
of  the  format  string  serves  to  separate  the  items  in 
the  diskette  file. 

The  LOC  function,  when  used  with  a  sequential  file, 
returns  the  number  of  records  that  have  been 
written  to  or  read  from  the  file  since  it  was  opened. 
(A  record  is  a  128-byte  block  of  data.)  The  LOF 
function  returns  the  number  of  bytes  allocated  to 
the  file.  This  number  is  always  a  multiple  of  128  (by 
rounding  upward,  if  necessary). 


Adding  Data  to  a  Sequential  File 

If  you  have  a  sequential  file  residing  on  diskette  and 
later  want  to  add  more  data  to  the  end  of  it,  you 
cannot  simply  open  the  file  for  output  and  start 
writing  data.  As  soon  as  you  open  a  sequential  file 
for  output,  you  destroy  its  current  contents. 
Instead,  you  should  open  the  file  for  APPEND. 
Refer  to  "OPEN  Statement"  in  Chapter  4  for 
details. 
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Random  Files 


Creating  and  accessing  random  files  requires  more 
program  steps  than  sequential  files,  but  there  are 
advantages  to  using  random  files.  For  instance, 
numbers  in  random  files  are  usually  stored  on 
diskette  in  binary  formats,  while  numbers  in 
sequential  files  are  stored  as  ASCII  characters. 
Therefore,  in  many  cases  random  files  require  less 
space  on  diskette  than  sequential  files. 

The  biggest  advantage  to  random  files  is  that  data 
can  be  accessed  randomly;  that  is,  anywhere  on  the 
diskette.  It  is  not  necessary  to  read  through  all  the 
information,  as  with  sequential  files.  This  is  possible 
because  the  information  is  stored  and  accessed  in 
distinct  units  called  records,  and  each  record  is 
numbered. 

Records  may  be  any  length  up  to  32767  bytes.  The 
size  of  a  record  is  not  related  to  the  size  of  a  sector 
on  the  diskette  (512  bytes).  BASIC  automatically 
uses  all  5 1 2  bytes  in  a  sector  for  information  storage. 
It  does  this  by  both  blocking  records  and  spanning 
sector  boundaries  (that  is,  part  of  a  record  may  be  at 
the  end  of  one  sector  and  the  other  part  at  the 
beginning  of  the  next  sector). 

The  statements  and  functions  that  are  used  with 
random  files  are: 


CLOSE 


CVI 

CVS 

LOC 

LOF 

MKD$ 

MKI$ 

MKS$ 


FIELD 
GET 


LSET/RSET 


OPEN 

PUT 

CVD 
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Creating  a  Random  File 


The  following  program  steps  are  required  to  create  a 
random  file. 

1.  Open  the  file  for  random  access.  The  example 
which  follows  to  illustrate  these  steps  specifies 
a  record  length  of  32  bytes.  If  the  record  length 
is  omitted,  the  default  is  128  bytes. 

2.  Use  the  FIELD  statement  to  allocate  space  in 
the  random  buffer  for  the  variables  that  will  be 
written  to  the  random  file. 

3.  Use  LSET  or  RSET  to  move  the  data  into  the 
random  buffer.  Numeric  values  must  be  made 
into  strings  when  placed  in  the  buffer.  To  do 
this,  use  the  "make"  functions:  MKI$  to  make 
an  integer  value  into  a  string,  MKS$  for  a 
single-precision  value,  and  MKD$  for  a 
double-precision  value. 

4.  Write  the  data  from  the  buffer  to  the  diskette 
using  the  PUT  statement. 

The  following  lines  illustrate  these  steps: 

100  OPEN  "FILE"  AS    S    LEN=32    Step  1 

200  I  ELD   ■■1,20  AS   N  ^  ,   ^   AS  A$  ,    8  AS  P$ 

'step  2 

300  .SET  N$  =  X$                                'step  3 

400  .SET  A$  =  M  KS  5  ( AMT )                  Still    -»tep  3 

500  -SET  PS  =  TEL$                            Still    s  Lep  3 

600  ST     1  ,  CODE                            1  step 

Note:  Do  not  use  a  string  variable  which  has 
been  defined  in  a  FIELD  statement  in  an  input 
statement  or  on  the  left  side  of  an  assignment 
(LET)  statement.  This  causes  the  pointer  for 
that  variable  to  point  into  string  space  instead 
of  the  random  file  buffer. 
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Look  at  PROGRAM3.  It  takes  information  that  is 
entered  at  the  keyboard  and  writes  it  to  a  random 
file.  Each  time  the  PUT  statement  is  executed,  a 
record  is  written  to  the  file.  The  two-digit  code  that 
is  input  in  line  30  becomes  the  record  number. 

Program  3 

1   REM  PROGRAM 3  -  creat.e  a  r.:indoM    \  i  !  e 
i  0  OPE  w  "Hit"  AS   -1    L  t.N- 3 2 
20  FIELD     I  ,20  AS  NS,   A  AS  A$  ,   8  ,\S  PS 
}0    INPUT   "2 -DIG  IT   CODE'";  CODE 
3P,   I  r    CODE  -99  THEN  CLOSE  :  END 
'tO    INi'-ir  "N,\ME";X$ 
50    INPUT  "AMOUNT"; AMT 
60    INPUT   ! 'PHONE' ';  TEL$  :  PRINT 
70   LSET  NS-XS 
80   LSET  A$-~M  KS  S  (  AMT  > 
50  LSET  P5--TF  i  S 
I  00  PUT    "  i  . CODE 
i  10  GOTO  30 

Accessing  a  Random  File 

The  following  program  steps  are  required  to  access  a 
random  file: 

1.  Open  the  file  for  random  access. 

2.  Use  the  FIELD  statement  to  allocate  space  in 
the  random  buffer  for  the  variables  that  will  be 
read  from  the  file. 

Note:    In  a  program  that  performs  both 
input  and  output  on  the  same  random  file, 
you  can  usually  use  just  one  OPEN 
statement  and  one  FIELD  statement. 

3.  Use  the  GET  statement  to  move  the  desired 
record  into  the  random  buffer. 


4.     The  data  in  the  buffer  may  now  be  accessed  by 
the  program.  Numeric  values  must  be 
converted  back  to  numbers  using  the 
"convert"  functions:  CVI  for  integers,  CVS  for 
single-precision  values,  and  CVD  for 

Hnilhlp-nrpricion  walnpc    ...  . 

ine  iollowmg  program  lines  illustrate  these  steps: 

1  00    )PEN   "F  !  EE"  AC    1    LEL=32        1  neo  1 
200   -  i  ELD  =1   20  /,S  LS ,   i+  AS  A$ ,   8  AS  r: 

t  ep  «.'. 

300   j  E  T     1  ,  C  0  D  E  '-ten  3 

A00    -RIM    N$  '-tei;  - 

300    AS  i  L  T   CVS  i  A$  '  •  st.  i  :  1  -\e-: 

PROGRAM4  accesses  the  random  file  "FILE"  that 
was  created  in  PROGRAM3.  By  entering  the 
two-digit  code  at  the  keyboard,  the  information 
associated  with  that  code  is  read  from  the  file  and 
displayed. 

Program  4 

1    r<A  •'   PLAAKmMm   -   c"K'^t"->-   d   '  jn.Ji.''   t  ','><.: 


'? '?  i- 

A"  L 
[■  2  L 

■'ML  E:i  / 

•"  1  ,   2  0 

f  \  5 

lEN-32 
NS  .   4  A) 

>  P  u  f 

'  Z  ~  U  1  Li 

AT  L 

')  5  ' 

IjE  -99  ' 
i  ,  CODE 

[  H  t  L 

CP  OS  E  : 

50  P 

ANT 

N  S 

50  p 

70 

A  0  b 

i  1,  : 
P  !  Ll 

<  AU 

PS  :  PR 

I  NT 

■  -■'    A  P 

The  LOC  function,  with  random  files,  returns  the 
"current  record  number."  The  current  record 
number  is  the  last  record  number  that  was  used  in  a 
GET  or  PUT  statement.  For  example,  the  statement 

If    ;  U'  1  !  >    P0  THEN  PAD 
uumuci  ui  me    i  is  mgner  tnan  5U. 
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An  Example  Program 

PROGRAM5  is  an  inventory  program  that 
illustrates  random  file  access.  In  this  program,  the 
record  number  is  used  as  the  part  number,  and  it  is 
assumed  the  inventory  will  contain  no  more  than 
100  different  part  numbers.  Lines  690-750  initialize 
the  data  file  by  writing  CHR$(25  5)  as  the  first 
character  of  each  record.  This  is  used  later  (line  ISO 
and  line  320)  to  determine  whether  an  entry  already 
exists  for  that  part  number. 

Lines  40-120  display  the  different  inventory 
functions  that  the  program  performs.  When  you 
type  in  the  desired  function  number,  line  140 
branches  to  the  appropriate  subroutine. 

Program  5 

'  :\'-    * !  H,v      .;'}.    ~. ..         A Hi.i  A;-  •  t 

-     r  F-  ;  S  1      .  *;  'f-S-    v  !      -  ." 

■■-  °R;N^  ;  .  Ti  ^ii.  i  hv-ntr,r ,  ;.-,r  ^  crj,  ■■ 
;-'K;N    l.  '  Aid  '  .  v  <:'.■>■" 

'  '••  ]  S  '   0-'i;St  b P '  C; W  5 1- '  '•  e  •••• 

H'h  1  '\         ''  f  !Vi  *hi- }  \  r  r  f ;  jr " 
h  [  \  i  ,        iNT;    ''N-L"Li'    "ClGlf.!?   ;  I ,  H  iJ  i f 
:'  ~i     ■   f';     '.^CI'.'F        J*>,H  "R;!(;    ""  *<  »  ■ 

:  :  •  ■  -t  t  ft  0 i .  0     • "  m  n  f  r  -. 

!      GOSUS  o?" 

130  IF  ASCiPtt.-  -2^.  "HEN  INPUT  •■J.eriinte'jA*: 

if  h*<  -  V  AND  m?>'   "V"  THEN  RL T URN 
1^0  l St '  F*=CHR* »0.' 

'NPl'T  "Desc-'ipiiort''.*DESC< 
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:v<  ■    '  .,i.*>  i  j  ur.. 

"4:;  ;N|:,T  "  P      ;J  e;'  Ip^jI'iP/, 

Jfu  ,  ,f:  R S  —  H I"  |$;RV 

280  f'.*    i ' ,  F'hR' % 


■~  <     .  . .  v- 


Hr'<    r  ' '  "Null 


H  b  T  U  ^  N 


J  4: 


r  i j  $ ,  -  h ^ :  i  ■  J', 


THt  h  f-Pi       afiL;!i  «?r,t?  y" ;  RfcJ'JRN 
d " 1 I  l  *  to  r  -_'C  *  '  ; 

HEN  Fr;I!^"nr:;.";1i;«Vi  it';c*":  GC 


<>  3*4--  "VI  \®t-  I  HEN  "PIN"  "Quantity  r-e*"  ;£>?.; 
jB<  pE'0>RN 

f-'ti  !  j-.!-  i<eis  below  reo'der  level 

60:'  rTR  I  =  |  TC  Inn 
o!"  GE T  #1, J 

tv"  ff  ASC«F*>=255  THEM  640 

63..;  :t  cviWKCVlfRU  THEN  PRINT  DJ;"  Quanti lv ";CV1  (Q$: 

TftE (50*  "Reorder  levei";CVI (R«S 
640  NEXT  ! 
650  RETURN 
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REM     qet  part  record 
6  -Ti;  INPUT  Tar !.  r-uifcer "  jpfiPTX 
680  IF  PARTv' !  OR  PARTMOC 

THEN  PPIMT  "Bdd  part  number GOTO  ft70 
E^St  fc[7  ^i.PARTX:  RETURN 

KOli  I  -  ;  JO  !Oi> 

.  ME.n  i 

,r:  ?nd  a?phr«tioi- 


B-14 


Performance  Hints 


•  If  you  do  not  use  random  files,  specify  /S:0  on 
the  BASIC  command  when  you  start  BASIC. 
This  will  save  128  bytes  times  the  number  of 
files  specified  in  the  /F:  option. 

•  BASIC  sets  up  three  files  by  default.  If  you  use 
less  than  three,  set  /V\files  when  you  start 
BASIC  with  the  BASIC  command.  Note  that 
the  screen,  keyboard,  and  printer  do  not  count 
as  files  unless  you  explicitly  OPEN  them. 

•  Sequential  files  use  a  buffer  of  128  bytes. 
Random  files  also  default  to  a  buffer  of  128 
bytes,  but  this  can  be  overridden  with  the  /S: 
option  on  the  BASIC  command.  There  is  no 
advantage  to  setting  /S:  to  a  number  greater 
than  the  largest  record  length  on  any  of  your 
random  files.  However,  the  combination  of  a 
record  length  of  5 1 2  and  /S:5 12  gives  improved 
performance  since  the  diskette  sector  size  is 
512  bytes. 

If  you  want  to  do  sequential  I/O,  but  still  want 
improved  performance,  you  can  use  random 
files  to  do  "pseudo-sequential"  I/O.  For 
example: 


!0  (>r£.N  "AbC"  F'OR  OUTPUT 

20  f  :.  R   ;  -  I    i  0  3000 

30  UH  NT   ■'•  i  ,  "MELH" 

-0  ui  n 

50  ■.  t  Ul-F.   •  !  :  END 


This  example  (lA)  uses  regular  sequential  I/O 
to  create  a  file  with  3000  items  in  it. 
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1    1   exai-p !  e  IB 

10  OPEN  "ABC"  FOR   I NPUT  AS   -  1 
20  OPEN  " D E F 1 1  FOR  OUTPUT  AS  "2 
30   I F  EOF( 1 )   THEN  CLOSE :  END 
40    I  NP'UT     1  ,  A^ 
50  PRINT  "2,A$ 
60  GOTO  30 
70  END 

This  example  (IB)  copies  the  sequential  file 
"ABC",  which  we  just  created,  to  a  file  named 
"DEF'\ 

For  the  next  examples  we  will  perform  the 
same  task  using  "pseudo-sequential"  I/O. 

1    1   examp  1  e  2 A 

10  OPEN  "PQR"  AS    -1    LEN  =  5!2 

15  ON  ERROR  GOTO  30 

20  FOR   1=1   TO  3000 

30  PR  I  NT   •■  1  ,  "MELH" 

^3  NEXT 

M5  PR!  NT    ■•' 1  AVeof" 

50  ON  ERROR  GOTO  0:   POT  -•  1  :  CLOSE 

60  END 

00  PUT      1  :  RESUME 

This  example  (2  A)  creates  a  file  with  3000  items 
using  random  I/O.  This  is  a  "pseudo- sequential" 
file. 


1  e  i 

b 

10 

OPEN  1 

POR: 

'  AS      1  11 

:n-5  1  2 

20 

OPEN  : 

X  v  I ' 

AS    "?.  LA 

:n-5 1 2 

30 

ON  ERP 

;oto  80 

•40 

GET   -  1 

50 

I  N  P  U  F 

::  1  i  , 

\S 

60 

PR  1  NT 

-'  '2  ,  / 

70 

IF  AS 

"/.- 

M,f"  THEN 

50  EL 

S  E 

ON 

C  o  r>  r 
u  i  \  !  \  k 

)R  GOTO  0 

PUT 

••■'2:  CLOSE 

30 

IF  LRU 

-50 

THEN  GET 

•■■  1  :  R 

::SUME 

This  final  example  copies  the 
"pseudo-sequential"  file  created  in  the 
previous  example  to  a  new  "pseudo-sequential" 
file  named  "XYZ".  It  takes  about  half  as  long  to 
run  as  the  example  using  sequential  I/O. 

The  technique  used  in  these  examples  involves 
detection  of  the  "FIELD  overflow"  error  (error 
50)  and  doing  the  appropriate  GET  or  PUT  to 
purge  the  buffer  (line  90  inexarnple  2Aand  line 
80  in  example  2B).  Note  also  that  a  dummy  end 
of  file  must  be  written  ("/eof '  in  the  example) 
and  checked  for  during  input.  Also,  the  INPUT 
and  PRINT  statements  use  only  single 
variables,  rather  than  a  list  of  variables. 

This  technique  is  useful  only  when  you  have 
more  than  one  file  open  at  a  time. 
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Appendix  C.  Machine  Language 

Subroutines 


This  appendix  describes  how  BASIC  interfaces  with 
machine  language  subroutines.  In  particular,  it 
describes: 

•  How  to  allocate  memory  for  the  subroutines 

•  How  to  get  the  machine  language  subroutine 
into  memory 

•  How  to  call  the  subroutine  from  BASIC  and 
pass  parameters  to  it 

This  appendix  is  intended  to  be  used  by  an 
experienced  machine  language  programmer. 


Reference  Material 

Rector,  Russell  and  Alexy,  George.  The  8086 
Book.  Osborne/McGraw-Hill,  Berkeley, 
California,  1980.  (includes  the  8088) 

Intel  Corporation  Literature  Department.  The 

8086  Family  User's  Manual,  9800722. 

3065  Bowers  Avenue,  Santa  Clara,  CA  95051. 

IBM  Corporation  Personal  Computer  library. 
Macro- Assembler \  Boca  Raton,  FL  33432. 

IBM  Corporation  Personal  Computer  library. 
Technical  Reference .  Boca  Raton,  FL  33432. 
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:ting  Memory  Aside  for 
ur  Subroutines 


BASIC  normally  uses  all  memory  available  from  its 
starting  location  up  to  a  maximum  of  64K-bytes. 
This  BASIC  workarea  contains  your  BASIC  program 
and  data,  along  with  the  interpreter  workarea  and 
BASIC'S  stack.  You  may  allocate  memory  space  for 
machine  language  subroutines  either  inside  or 
outside  of  this  BASIC  64K  workarea.  Where  you 
decide  to  put  the  routines  depends  on  the  total 
amount  of  available  memory  and  the  size  of  the 
applications  to  be  loaded. 

Your  system  needs  more  than  64K-bytes  of  memory 
if  you  want  to  put  your  machine  language 
subroutines  outside  BASIC'S  64K  workarea.  If  you 
are  using  Disk  or  Advanced  BASIC,  DOS  takes  up 
approximately  12K-bytes,  and  BASIC  takes  up 
another  lOK-bytes,  so  you  need  at  least  a 
96K-byte  system  in  order  for  there  to  be  room 
outside  the  BASIC  workarea  for  the  machine 
language  subroutines. 

Outside  the  BASIC  Workarea:    If  your  system  has 
enough  memory  that  you  can  put  your  subroutines 
outside  the  BASIC  64K-byte  workarea,  you  don't 
have  to  do  anything  to  reserve  that  area.  You  use  the 
DEF  SEG  statement  to  address  the  external 
subroutine  area  outside  the  BASIC  workarea. 

For  example,  in  a  96K-byte  system,  to  specify  an 
address  in  the  upper  4K-by  tes  of  memory,  you  could 
use: 

This  statement  specifies  a  segment  starting  at 
hexadecimal  location  17000  (92K). 


Inside  the  BASIC  Workarea:    In  order  to  keep 
BASIC  from  writing  over  your  subroutines  in 
memory,  use  either: 

•  The  CLEAR  statement,  which  is  available  in  all 
versions  of  BASIC 

•  The  /M:  option  on  the  BASIC  command  to  start 
Disk  and  Advanced  BASIC  from  DOS 

Only  the  highest  memory  locations  can  be  set  aside 
for  subroutines.  For  example,  to  reserve  the  highest 
4K-byte  area  of  BASIC'S  64K-byte  workarea  for 
your  machine  language  subroutines,  you  could  use: 

10   f.LPAR    ,  sHF000 
or  start  BASIC  with  the  DOS  command: 


BAcj  I  C   /M  :  -;HF000 

Either  of  these  statements  restricts  the  size  of  the 
BASIC  workarea  to  hex  F000  (60K)  bytes,  so  you 
can  use  the  uppermost  4K-bytes  for  machine 
language  subroutines. 


Getting  the  Subroutine  Code  into 
Memory 


The  following  are  offered  as  suggestions  as  to  how 
machine  language  subroutines  can  be  loaded.  We 
don't  describe  all  possible  situations. 

Two  common  ways  to  get  a  machine  language 
program  into  memory  are: 

•  Poking  it  into  memory  from  your  BASIC 
program 

•  Loading  it  from  a  file  on  diskette  or  cassette 
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Poking  a  Subroutine  into  Memory 


You  can  code  relatively  short  subroutines  in 
machine  language  and  use  the  POKE  statement  to 
put  the  code  into  memory.  In  this  way,  the 
subroutine  actually  becomes  a  part  of  your  BASIC 
program.  One  way  to  do  this  is: 

1.  Determine  the  machine  code  for  your 
subroutine. 

2.  Put  the  hex  value  (&Hxx  format)  of  each  byte 
of  the  code  into  DATA  statements. 

3.  Execute  a  loop  which  reads  each  data  byte,  and 
then  pokes  it  into  the  area  you've  selected  for 
the  subroutine  (see  the  preceding  discussion). 

4.  After  the  loop  is  complete,  the  subroutine  is 
loaded.  If  you  are  going  to  call  the  subroutine 
using  the  USR  function,  then  you  must  execute 
a  DEF  USR  statement  to  define  the  entry 
address  of  the  subroutine;  if  you  are  going  to 
call  the  subroutine  using  the  CALL  statement, 
you  must  set  the  value  of  the  subroutine 
variable  to  the  subroutine's  entry  address. 

For  example: 


20  DEf"  S P:G=  &H  1700 

30  FOK   1-0  TO  21 

!\0  RC/iD  J 

50    POKE    i  ,  J 

60  N  E  X T 

70  SUBRT=0 

30  A-2  :B  =  3:O0 

90  CALF  S  LIB  KT  i  A  ,  B  ,  C  ) 

S00  PR. 'NT  C 

i  1  0  END 

120  DATA  SH55,&H8B,SHF.C,&H8B,&H76,5H0A 
130  DATA  SH8B,Sri0A,&H8B,SH76,&H08 
U\0  DATA  &H03,&H04,&H8B,&H7E,&H06 
150  DATA  SH8q,&H05,&H5D,&HCA,&H06,&H00 
RUN 
q 

Ok 


Loading  the  Subroutine  from  a  File 


You  use  the  BASIC  BLOAD  command  to  load  a 
memory  image  file  directly  into  memory.  The 
memory  image  can  be  a  machine  language 
subroutine  which  was  saved  using  the  BSAVE 
command.  Of  course,  that  leads  to  the  question  of 
how  the  subroutine  got  there  in  the  first  place.  The 
machine  language  subroutine  may  be  an  executable 
file  which  was  created  by  the  linker  from  DOS,  and 
which  was  placed  into  memory  using  DEBUG. 
DEBUG  and  the  linker  are  explained  in  the  IBM 
Persona/  Computer  Disk  Operating  System  manual. 

The  following  is  a  suggested  way  to  use  BLOAD  to 
get  such  a  machine  language  subroutine  into 
memory: 

1.  Use  the  linker  to  produce  an  .EXE  file  of  your 
routine  (let's  call  it  ASMROUT.EXE)  so  it  will 
load  at  the  HIGH  end  of  memory. 


2.     Load  BASIC  under  DEBUG  by  entering: 

DEBUG  BAS I C. COM 


3.  Display  the  registers  (use  the  R  command)  to 
find  out  where  BASIC  was  put  in  memory. 
Record  the  values  contained  in  the  registers 
(CS,  IP,  SS,  SP,  DS,  ES)  for  later  reference. 

4.  Use  DEBUG  to  load  the  .EXE  file  (your 
subroutine)  into  HIGH  memory,  where  it  will 
overlay  the  transient  portion  of 
COMMAND.COM. 


N  ASMROUT.EXE 
L 
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5.  Display  the  registers  (use  the  R  command)  to 
find  out  where  the  subroutine  was  placed  in 
memory.  Record  the  values  contained  in  the  CS 
and  IP  registers  for  later  use. 

6.  Reset  the  registers  (use  the  R  command)  back 
to  the  values  they  contained  when  BASIC.COM 
was  originally  loaded,  using  the  values  noted  in 
step  3. 

7.  Use  the  G  command  to  branch  to  the  BASIC 
entry  point  and  to  set  breakpoints  (if  desired)  in 
the  machine  language  subroutine. 

8.  When  BASIC  prompts,  load  your  BASIC 
application  program  and  edit  the  DEF  SEG  and 
either  the  DEF  USR  statement  or  the  value  of 
the  CALL  variable  to  correspond  with  the 
location  of  the  subroutine  as  determined  when 
you  loaded  the  subroutine  in  step  5. 

•  Use  the  previously  recorded  value  in  the 
CS  register  for  DEF  SEG 

•  Use  the  previously  recorded  value  in  the  IP 
register  for  the  DEF  USR  or  the  variable 
value  of  the  CALL 

9.  In  direct  mode  in  BASIC,  enter  a  BSAVE 
command  to  save  the  subroutine  area.  Use  the 
starting  location  defined  by  the  CS  and  IP 
registers  when  the  subroutine  was  loaded  in 
step  5,  and  the  code  length  printed  on  the 
assembler  listing  or  LINK  map.  (Refer  to 
"BSAVE  Command"  in  Chapter  4.) 

10.  Edit  your  BASIC  application  program  so  it 
contains  a  BLOAD  statement  after  the  DEF 
SEG  that  sets  the  proper  value  of  CS  for  the 
subroutine. 
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Note:    If  the  machine  language  routine  is 
self-relocatable,  BLOAD  can  be  used  to 
put  the  subroutine  some  place  other  than 
where  the  linker  originally  placed  it.  If  you 
make  such  a  change,  be  sure  to  make  a 
corresponding  change  to  the  DEF  SEG 
statement  associated  with  the  call  so  that 
BASIC  can  find  the  subroutine  at 
execution  time. 

Some  suggestions  for  alternate  locations 
for  the  subroutine  are: 

•  An  unused  screen  buffer 

•  An  unused  file  buffer  (located  with 
VARPTR(#/)) 

•  A  string  variable  area  located  with 
VAKPTR(strit2gvar) 

(See  'BLOAD  Command"  and  "VARPTR 
Function"  in  Chapter  4.) 

1 1 .   Save  the  resulting  modified  BASIC  application. 

Some  Notes  on  Using  DEBUG  with  BASIC: 

When  you  run  BASIC  under  DEBUG,  BASIC  is 
loaded  after  DEBUG  in  memory,  so  DEBUG  is  not 
written  over  if  you  load  a  large  BASIC  program.  If 
you  set  breakpoints  in  your  machine  language 
subroutine,  they  return  you  to  DEBUG.  The 
SYSTEM  command  also  returns  you  from  BASIC  to 
DEBUG. 
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Calling  the  Subroutine  from 
Your  BASIC  Program 


All  versions  of  BASIC  have  two  ways  to  call  machine 
language  subroutines:  the  USR  function,  and  the 
CALL  statement.  This  section  describes  the  use  of 
both  USR  and  CALL. 


Whether  you  call  your  machine  language 
subroutines  with  CALL  or  with  the  USR  function, 
you  must  keep  the  following  things  in  mind: 

Entering  the  Subroutine 

•  At  entry,  the  segment  registers  DS,  ES,  and  SS 
are  all  set  to  the  same  value,  the  address  of 
BASIC'S  data  space  (the  default  for  DEF  SEG). 

•  At  entry,  the  code  segment  register,  CS, 
contains  the  current  value  specified  in  the  latest 
DEF  SEG.  If  DEF  SEG  has  not  been  specified, 
or  if  the  latest  DEF  SEG  did  not  specify  an 
override  value,  the  value  in  CS  is  the  same  as  in 
the  other  three  segment  registers. 


String  Arguments 

•     If  an  input  argument  is  a  string,  the  value 
received  in  the  argument  is  the  address  of  a 
three-byte  area  called  the  string  descriptor: 

1 .  Byte  0  of  the  string  descriptor  contains  the 
length  of  the  string  (0  to  255). 

2.  Byte  1  of  the  string  descriptor  contains  the 
lower  8  bits  of  the  offset  of  the  string  in 
BASIC's  data  space. 
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3.  Byte  2  of  the  string  descriptor  contains  the 
higher  8  bits  of  the  offset  of  the  string  in 
BASIC's  data  space. 

The  string  itself  is  pointed  to  by  the  last  two 
bytes  of  the  string  descriptor. 

Warning: 

The  subroutine  must  not  change  the 
contents  of  any  of  the  three  bytes  of  the  string 
descriptor. 

The  subroutine  may  change  the  content  of  the 
string  itself,  but  not  its  length. 

If  the  subroutine  changes  a  string,  be  aware  that 
this  may  modify  your  program.  The  following 
example  may  change  the  string  "TEXT"in  the 
BASIC  program. 

AS  -  "TEXT" 
CALL  SUBRT(A$J 

However,  the  next  example  does  not  modify 
the  program,  because  the  string  concatenation 
causes  BASIC  to  copy  the  string  into  the  string 
space  where  it  may  be  safely  changed  without 
affecting  the  original  text. 

AS  =  1 1 B A S  I  C" 
CALL  SUBRT(A$) 


Returning  from  the  Subroutine 

•  The  return  to  BASIC  must  be  by  an 
inter-segment  RET  instruction.  (The 
subroutine  is  a  FAR  procedure.) 

•  At  exit,  all  segment  registers  and  the  stack 
pointer,  SP,  must  be  restored.  All  other 
registers  (and  flags)  may  be  altered. 
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•  The  stack  pointer,  at  entry,  indicates  a  stack 
that  has  only  16  bytes  (eight  words)  available 
for  use  by  the  subroutine.  If  more  stack  space  is 
needed,  the  subroutine  must  set  up  its  own 
stack  segment  and  stack  pointer.  You  should 
make  sure  that  the  location  of  the  current  stack 
is  recorded  so  its  pointer  can  be  restored  just 
prior  to  return. 

•  If  interrupts  were  disabled  by  the  subroutine, 
they  should  be  enabled  prior  to  return. 

CALL  Statement 

Machine  language  subroutines  may  be  called  using 
the  BASIC  CALL  statement.  The  format  of  the 
CALL  statement  is: 

CALL  numvar  {{variable  list)] 

numvar        is  the  name  of  a  numeric  variable.  Its 
value  is  the  offset,  from  the  segment  set 
by  DEF  SEG,  that  is  the  starting  point  in 
memory  of  the  subroutine  being  called. 

variable  list  contains  the  variables,  separated  by 
commas,  that  are  to  be  passed  as 
arguments  to  the  routine.  (The 
arguments  cannot  be  constants.) 

Execution  of  a  CALL  statement  causes  the 
following: 

1.     For  each  variable  in  the  variable  list,  the 
variable's  location  is  pushed  onto  the  stack. 
The  location  is  specified  as  a  two-byte  offset 
into  BASIC'S  data  segment  (the  default  DEF 
SEG). 
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2.  The  return  address  specified  in  the  CS  register 
and  the  offset  are  pushed  onto  the  stack. 

3.  Control  is  transferred  to  the  machine  language 
routine  using  the  segment  address  specified  in 
the  last  DEF  SEG  statement  and  the  offset 
specified  by  the  value  of  numvar. 


Notes  for  the  CALL  Statement 

•  You  can  return  values  to  BASIC  through  the 
arguments  by  changing  the  values  of  the 
variables  in  the  argument  list. 

•  If  the  argument  is  a  string,  the  offset  for  the 
argument  points  to  the  three-byte  string 
descriptor  as  explained  previously. 

•  The  called  routine  must  know  how  many 
arguments  were  passed.  Parameters  are 
referenced  by  adding  a  positive  offset  to  BP 
after  the  called  routine  moves  the  current  stack 
pointer  into  BP.  The  first  instructions  in  the 
subroutine  should  be: 

PUSH  BP         ;SAVE  BP 

MOV  BP,SP      ;M0VE   SP  TO  BP 

The  offset  into  the  stack  of  any  one  particular 
argument  is  calculated  as  follows: 

offset  from  BP  =  2*(/z-w)+6 

where: 

n      is  the  total  number  of  arguments  passed. 

m  is  the  position  of  the  specific  argument  in  the 
argument  list  of  the  BASIC  CALL  statement  {m 
may  range  from  1  to  n). 
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Example:  The  following  example  adds  the  values 
in  A%  and  B%  and  stores  the  result  in  C%: 


The  following  statements  are  in  BASIC: 

100  A  -2:  B'=3 

200     DEF  SEG=&H27E0 

250     6L0AD  "SUBRT.  EXE!l,0 

300  SUBRT=0 

400     CALL  SUBRT   (A  -  ,  B -  ,  C - i 

500  FRINT  (V 

Note:    Line  200  sets  the  segment  to  location 
hex  27EOO.  SUBRT  is  set  to  0  so  that  the  call 
to  SUBRT  executes  the  subroutine  at 
location  &H27E00. 

The  following  statements  are  in  IBM  Personal 
Computer  Macro- Assembler  source  code: 

CSEG  SEGMENT 


Note:    When  you  call  a  routine  using  the 
CALL  statement,  the  routine  must  return 
with  a  RET  n,  where  n  is  2  times  the  number 
of  arguments  in  the  variable  list.  This  is 
necessary  to  adjust  the  stack  to  the  point  at 
the  start  of  the  calling  sequence. 


SUBRT 


ASSUME  CS : C5EG 
PROC  FAR 

PUSH  BP  ; 
MOV  BP.SP 

MOV   SI,    BP  '+10  ; 

MOV  AX , '  S  I  ; 

MOV  S I ,    BP  +8  ; 

ADD  AX  ,    S  !  ; 

MOV  D I ,   BP  +6  ; 

MOV  '  D I  .  , AX  ; 

POP  BP  ; 

RET  6  ; 
EN  DP 
ENDS 
END 


;SAVE  BP 

;SET  BASE   P ARM  LIST 
; GET  ADDR   PARM  A 
;GET   VALUE   OF  A 
; GET  A  DDR  PARM  B 
; ADD  VALUE  B  TO  REG 


; G  E  T  A  DDR  PARM  C 
;PASS   BaCK  SUM 
;  RESTORE  BP 

; FAR  RETURN  TO  BAS ! C 


As  another  example: 


10   DEF  i  NT  A-Z 

100   DEF  S  EG-&H 1 800 

1  10  BLOAD  MSUBRT.EXE!,,0 

120  SUBRT-0 

1 30  CALL  SUBRT  (7\,B$,C> 

The  following  sequence  of  Macro- Assembler  code 
shows  how  the  arguments  (including  the  address  of  a 
string  descriptor)  are  passed  and  accessed,  and  how 
the  result  is  stored  in  variable  C: 


BP 

EL  , 

SP 

;  G  E  T 

MOV 

B  X , 

BP  t8 

;  G  E  T 

MOV 

L  L  , 

BX 

;  GF  T 

000 

L)  X  , 

1  BX 

;  GET 

E  BP 

CURRENT   c.  T  K  POO  !  TIC'I    i  NT . 
A  DDR  OF   BS   STR  NG   DF  ' 
LENGTH   OF    BS    INFO  Oi 
ADDR  OF  BS  T  L  >  "i    INTO  [;.. 


POO  '  I ,    BP  +10   ; GET   A DDR  Or  A     N T C  S ! 

OOP  Di  ,   BP  t-6     ;CFT  /.DDR  OF  0    I  NfO  D I 

'•'.Oi  S  WORD  ;  A  PC  RE   VAR  |  ABLt   m  SNTO 

POP  BP  ;  R E  S  T  0 R F  BP 

R  E  6  ;  RESTORE   v-.i-\CE,  RETURN 


Warning: 

It  is  entirely  up  to  you  to  make  sure  that  the 
arguments  in  the  CALL  statement  match  in 
number,  type,  and  length  with  the  arguments 
expected  by  the  subroutine. 

In  the  preceding  example,  the  instruction  MOVS 
WORD  copies  only  two  bytes  because  variables  A 
and  C  are  integers.  However,  if  A  and  C  are 
single-precision,  four  bytes  must  be  copied;  if  A  and 
C  are  double-precision,  eight  bytes  must  be  copied. 
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USR  Function  Calls 


The  other  way  to  call  machine  language  subroutines 
from  BASIC  is  with  the  USR  function.  The  format  of 
the  USR  function  is: 

USR[n](arg) 

n      must  be  a  single  digit  in  the  range  0  through  9. 

arg    is  any  numeric  expression  or  a  string  variable 
name, 

n  specifies  which  USR  routine  is  being  called,  and 
corresponds  with  the  digit  supplied  in  the  DEF  USR 
statement  for  that  routine.  If  n  is  omitted,  USRO  is 
assumed.  The  address  specified  in  the  DEF  USR 
statement  determines  the  starting  address  of  the 
subroutine.  Even  if  the  subroutine  does  not  require 
an  argument,  a  dummy  argument  must  still  be 
supplied. 

When  the  USR  function  is  called,  register  AL 
contains  a  value  that  specifies  the  type  of  argument 
that  was  supplied.  The  value  in  AL  will  be  one  of  the 
following: 

Value  in  AL   Type  of  Argument 

2  Two-byte  integer  (two's  complement) 

3  String 

4  Single-precision  number 

8  Double-precision  number 

If  the  argument  is  a  string,  the  DX  register  points  to 
the  three-byte  string  descriptor.  (See  "Common 
Features  of  CALL  and  USR,"  described  previously.) 
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If  the  argument  is  a  number  and  not  a  string,  the 
value  of  the  argument  is  placed  in  the  Floating  Point 
Accumulator  (FAC),  which  is  an  eight-byte  area  in 
BASIC's  data  space.  In  this  case,  the  BX  register 
contains  the  offset  within  the  BASIC  data  space  to 
the  fifth  byte  of  the  eight-byte  FAC.  For  the 
following  examples,  assume  that  the  FAC  is  in  bytes 
hex  49F  through  hex  4A6;  that  is,  BX  contains  hex 
4A3: 

If  the  argument  is  an  integer: 

•  Hex  4A4  contains  the  upper  8  bits  of  the 
argument. 

•  Hex  4A3  contains  the  lower  8  bits  of  the 
argument. 

If  the  argument  is  a  single-precision  number: 

•  Hex4A6  contains  the  exponent  minus  128,  and 
the  binary  point  is  to  the  left  of  the  most 
significant  bit  of  the  mantissa.  Hex  4A5 
contains  the  highest  7  bits  of  the  mantissa  with 
the  leading  1  suppressed  (implied).  Bit  7  is  the 
sign  of  the  number  (0  =  positive;  1  =  negative). 

•  Hex  4A4  contains  the  middle  8  bits  of  the 
mantissa. 


•     Hex  4A3  contains  the  lowest  8  bits  of  the 
mantissa. 


If  the  argument  is  a  double-precision  number: 

•     Hex  4A3  through  hex  4A6  are  the  same  as 
described  under  single-precision  floating-point 
number  in  the  preceding  paragraph. 


Hex  49F  through  Hex  4A2  contain  four  more 
bytes  of  the  mantissa  (hex  49F  contains  the 
lowest  8  bits). 
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Usually,  the  value  returned  by  a  USR  function  is  the 
same  type  (integer,  string,  single-precision,  or 
double-precision)  as  the  argument  that  was  passed 
to  it.  However,  a  numerical  argument  of  the 
function,  regardless  of  its  type,  may  be  forced  to  an 
integer  value  by  calling  the  FRCINT  routine  to  get 
the  integer  equivalent  of  the  argument  placed  into 
register  BX. 

If  the  value  being  returned  by  the  function  is  to  be 
an  integer,  place  the  resulting  value  into  the  BX 
register.  Then  make  a  call  to  MAKINT  just  prior  to 
the  inter-segment  return.  This  passes  the  value  back 
to  BASIC  by  placing  it  into  the  FAC. 

The  methods  for  accessing  FRCINT  and  MAKINT 
are  shown  in  the  following  example: 

100  DEF  SEG=&Hl800 

120  B  LOAD  "SUBRT . EXE" ,0 
130  DEF  USR0=0 

140  X       5    'Hole  that  X   is  single-precision 
150  V  -  USR0 (X) 
160  PR  i  NT  Y 

At  location  1800:0  (segment: offset),  the  following 
Macro- Assembler  language  routine  has  been  loaded. 
The  routine  doubles  the  argument  passed  and 
returns  an  integer  result: 


StG            SFGMENT  ,J  0F600H   ; BASE  OF  BASIC  ROM 

ORG       3  ;  0 F  f N  ["  T  TO   FORCE  INTEGER 
PRC  I  M      I  ABE  FAR 

CRC       /  ;OFf"SF  I    TO  MAKE    I  NTECER 
Mm'  I  NT     LABF  I  E/.R 
SEC  FNEr. 


RFRG 


G  E  GME  NT 

PROl  f  „H  ;LN1 K '    EC  I  NT 

f  AL  L  f  RC  I  NT   ;  FORCl   ARC    I  t,   FA(.    I  N T 0  B< 

AD j  BX  , BX      ; ' BX     -     BX  2 

f.Al  i  MAH  I  NT    ;  r-CT    i  N!    R>LT    IN   BX    I  N  T  G   F <  ■  L 

RE1  :    N  ""[_■<-  '■  E  G  M,  F  N  T    RETURN    10  P,      !  C 

[  N  DP 

END 


Note:    FRCINT  and  MAKINT  perform 
inter-segment  returns.  You  should  make  sure 
that  the  calls  to  FRCINT  and  MAKINT  are 
defined  by  a  FAR  procedure. 
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Appendix  D.  Converting  Programs 

to  IBM  Personal 
Computer  BASIC 

Since  IBM  Personal  Computer  BASIC  is  very  similar 
to  many  microcomputer  BASICs,  the  IBM  Personal 
Computer  will  support  programs  written  for  a  wide 
variety  of  microcomputers.  If  you  have  programs 
written  in  a  BASIC  other  than  IBM  Personal 
Computer  BASIC,  some  minor  adjustments  may  be 
necessary  before  running  them  with  IBM  Personal 
Computer  BASIC.  Here  are  some  specific  things  to 
look  for  when  converting  BASIC  programs. 

File  I/O 

In  IBM  Personal  Computer  BASIC,  you  read  and 
write  information  to  a  file  on  diskette  or  cassette  by 
opening  the  file  to  associate  it  with  a  particular  file 
number;  then  using  particular  I/O  statements  which 
specify  that  file  number.  I/O  to  diskette  and  cassette 
files  is  implemented  differently  in  some  other 
BASICs.  Refer  to  the  section  in  Chapter  3  called 
"Files,"  and  to  "OPEN  Statement"  in  Chapter  4  for 
more  specific  information. 

Also,  in  IBM  Personal  Computer  BASIC,  random 
file  records  are  automatically  blocked  as 
appropriate  to  fit  as  many  records  as  possible  in  each 
sector. 

Graphics 

How  you  draw  on  the  screen  varies  greatly  between 
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IF.. .THEN 


The  IF  statement  in  IBM  Personal  Computer  BASIC 
contains  an  optional  ELSE  clause,  which  is 
performed  when  the  expression  being  tested  is  false. 
Some  other  BASICs  do  not  have  this  capability.  For 
example,  in  another  BASIC  you  may  have: 

10  IF  A=B  THEN  30 

20  PRINT  "NOT  EQUAL' 1       GOTO  ^0 

30  PRINT  "EQUAL1 1 

k®  REM  CONTINUE 

This  sequence  of  code  will  still  function  correctly  in 
IBM  Personal  Computer  BASIC,  but  it  may  also  be 
conveniently  recoded  as: 

10    IF  A-3   THEN  PRINT  "EQUAL11  ELSE   PRIM   "NOT  EQUAL' 
20  REM  CONTINUE 

IBM  Personal  Computer  BASIC  also  allows  multiple 
statements  in  both  the  THEN  and  ELSE  clauses. 
This  may  cause  a  program  written  in  another  BASIC 
to  perform  differently.  For  example: 

10  IF  A= B  THEN  GOTO  100  •  PRINT  "NOT  EQUAL" 
20  REM  CONTINUE 

In  some  other  BASICs,  if  the  test  A=B  is  false, 
control  branches  to  the  next  statement;  that  is,  if  A  is 
not  equal  to  B,  "NOT  EQUAL"  is  printed.  In  IBM 
Personal  Computer  BASIC,  both  GOTO  100  and 
PRINT  "NOT  EQUAL"  are  considered  to  be  part  of 
the  THEN  clause  of  the  IF  statement.  If  the  test  is 
false,  control  continues  with  the  next  program  line; 
that  is,  to  line  20  in  this  example.  PRINT  "NOT 
EQUAL"  can  never  be  executed. 

This  example  can  be  recoded  in  IBM  Personal 
Computer  BASIC  as: 

10   IF  A=B  THEN  100  ELSE  PRINT  "NOT  EQUAL" 
20  REM  CONTINUE 
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Line  Feeds 


In  other  BASICs,  when  you  enter  a  line  feed,  a  line 
feed  character  is  actually  inserted  into  the  text.  On 
the  IBM  Personal  Computer,  entering  a  line  feed 
will  pad  the  rest  of  the  display  line  with  spaces  —  it 
does  not  insert  the  line  feed  character.  If  you  try  to 
load  a  program  with  line  feed  characters  in  it,  you 
will  get  a  "Direct  statement  in  file"  error. 


Logical  Operations 


In  IBM  Personal  Computer  BASIC,  logical 
operations  (NOT,  AND,  OR,  XOR,  IMP,  and  EQV) 
are  performed  bit-by-bit  on  integer  operands  to 
produce  an  integer  result.  In  some  other  BASICs, 
the  operands  are  considered  to  be  simple  "true" 
(non-zero)  or  "false"  (zero)  values,  and  the  result  of 
the  operation  is  either  true  or  false.  As  an  example 
of  this  difference,  consider  this  small  program: 

10  A=9:  B=2 

20    IF  A  AND  B   THEN  PRINT   "BOTH  A.  AND  B  ARB  TRUF" 

This  example  in  another  BASIC  will  perform  as 
follows:  A  is  non-zero,  so  it  is  true;  B  is  also  non-zero, 
so  it  is  also  true;  because  both  A  and  B  are  true,  A 
AND  B  is  true,  so  the  program  prints  BOTH  A  AND 
B  ARE  TRUE. 

However,  IBM  Personal  Computer  BASIC 
calculates  it  differently:  A  is  1001  in  binary  form, 
and  B  is  0010  in  binary  form,  so  A  AND  B 
(calculated  bit-by-bit)  is  0000,  or  zero;  zero 
indicates  false,  so  the  message  is  not  printed,  and  the 
program  continues  with  the  next  line. 

This  can  affect  not  only  tests  made  in  IF  statements, 
but  calculations  as  well.  To  get  similar  results, 
recode  logical  expressions  like  the  following: 

10  A=9:  B=2 

20    I  F   (A-    0)   AND   ( B-  0) 

THEN  PRINT  "BOTH  A  AND  B  ARE  TRUE1 1 
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MAT  Functions 


Programs  using  the  MAT  functions  available  in 
some  BASICs  must  be  rewritten  using  FOR.. .NEXT 
loops  to  execute  properly. 


Multiple  Assignments 

Some  BASICs  allow  statements  of  the  form: 

10  LET  B-C=0 

to  set  B  and  C  equal  to  zero.  IBM  Personal 
Computer  BASIC  would  interpret  the  second  equal 
sign  as  a  logical  operator  and  set  B  equal  to  -1  if  C 
equaled  0.  Instead,  convert  this  statement  to  two 
assignment  statements: 

10  C=0:B=0 


Multiple  Statements 

Some  BASICs  use  a  backslash  (  \ )  to  separate 
multiple  statements  on  a  line.  With  IBM  Personal 
Computer  BASIC,  be  sure  all  statements  on  a  line 
are  separated  by  a  colon  (:). 


PEEKs  and  POKEs 

Many  PEEKs  and  POKEs  are  dependent  on  the 
particular  computer  you  are  using.  You  should 
examine  the  purpose  of  the  PEEKs  and  POKEs  in  a 
program  in  another  BASIC,  and  translate  the 
statement  so  it  performs  the  same  function  on  the 
IBM  Personal  Computer. 
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Relational  Expressions 


In  IBM  Personal  Computer  BASIC,  the  value 
returned  by  a  relational  expression,  such  as  A>B,  is 
either  -1,  indicating  the  relation  is  true,  of  0, 
indicating  the  relation  is  false.  Some  other  BASICs 
return  a  positive  1  to  indicate  true.  If  you  use  the 
value  of  a  relational  expression  in  an  arithmetic 
calculation,  the  results  are  likely  to  be  different 
from  what  you  want. 


Remarks 

Some  BASICs  allow  you  to  add  remarks  to  the  end  of 
a  line  using  the  exclamation  point  (!).  Be  sure  to 
change  this  to  a  single  quote  (')  when  converting  to 
IBM  Personal  Computer  BASIC. 


Rounding  of  Numbers 

IBM  Personal  Computer  BASIC  rounds  single-  or 
double-precision  numbers  when  it  requires  an 
integer  value.  Many  other  BASICs  truncate  instead. 
This  can  change  the  way  your  program  runs,  because 
it  affects  not  only  assignment  statements  (for 
example,  I%=2.5  results  in  1%  equal  to  3),  but  also 
affects  function  and  statement  evaluations  (for 
example,  TAB(4.5)  goes  to  the  fifth  position,  A(l  .5) 
is  the  same  as  A(2),  andX=l  1.5  MOD4  will  result  in 
a  value  of  0  for  X).  Note  in  particular  that  rounding 
may  cause  IBM  Personal  Computer  BASIC  to  select 
a  different  element  from  an  array  than  another 
BASIC  —  possibly  one  that  is  out  of  range! 


Sounding  the  Bell 


Some  BASICs  require  PRINT  CHR$(7)  to  send  an 
ASCII  bell  character.  In  IBM  Personal  Computer 
BASIC,  you  may  replace  this  statement  with  BEEP, 
although  it  is  not  required. 
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String  Handling 


String  Length:    Since  strings  in  IBM  Personal 
Computer  BASIC  are  all  variable  length,  you  should 

which  dimensions  a  string  array  for  J  elements  of 
length  I,  should  be  converted  to  the  IBM  Personal 
Computer  BASIC  statement  DIM  A$(J). 

Concatenation:    Some  BASICs  use  a  comma  or 
ampersand  for  string  concatenation.  Each  of  these 
must  be  changed  to  a  plus  sign,  which  is  the  operator 
for  IBM  Personal  Computer  BASIC  string 
concatenation. 

Substrings:    In  IBM  Personal  Computer  BASIC, 
the  MID$,  RIGHT$,  and  LEFT$  functions  are  used 
to  take  substrings  of  strings.  Forms  such  as  A$(I)  to 
access  the  Ith  character  in  A$,  or  A$(IJ)  to  take  a 
substring  of  A$  from  positin  I  to  position  J,  must  be 
changed  as  follows: 

Other  BASIC     IBM  Personal  Computer  BASIC 

X$=A$(iJ  X$=MID$(A$, I ,1) 

X$=A${ !  ,J)  X$  =  M I D$ ( A$ ,  I  ,J-I+1) 

If  the  substring  reference  is  on  the  left  side  of  an 
assignment  and  X$  is  used  to  replace  characters  in 
A$,  convert  as  follows: 

Other  BASIC     IBM  Personal  Computer  BASIC 

A 5?  (  I  )=X$  Ml  D$(A$,  I  ,  1  )=X$ 

A$(  I  ,J)=X$        Ml  D$  (A$  ,  I  ,J--  1+1 )=X$ 
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Use  of  Blanks 


Some  BASICs  allow  statements  with  no  separation 
of  keywords: 

20FOR I =1T0X 

With  IBM  Personal  Computer  BASIC  be  sure  all 
keywords  are  separated  by  a  space: 

20  FOR   1=1   TO  X 

Other 

The  BASIC  language  on  another  computer  may  be 
different  from  the  IBM  Personal  Computer  BASIC 
in  other  ways  than  those  listed  here.  You  should 
become  familiar  with  IBM  Personal  Computer 
BASIC  as  much  as  possible  in  order  to  be  able  to 
appropriately  convert  any  function  you  may 
require. 
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Appendix  E.  Mathematical  Functions 


Functions  that  are  not  intrinsic  to  IBM  Personal 
Computer  BASIC  may  be  calculated  as  follows. 


Function 


Equivalent 


Logarithm  to  base  B 

Secant 

Cosecant 

Cotangent 

Inverse  sine 

Inverse  cosine 

Inverse  secant 

Inverse  cosecant 

Inverse  cotangent 
Hyperbolic  sine 
Hyperbolic  cosine 
Hyperbolic  tangent 

Hyperbolic  secant 
Hyperbolic  cosecant 
Hyperbolic 
cotangent 
Inverse  hyperbolic 
sine 

Inverse  hyperbolic 

cosine 
Inverse  hyperbolic 

tangent 
Inverse  hyperbolic 

secant 
Inverse  hyperbolic 

cosecant 

Inverse  hyperbolic 
cotangent 


LOGB(X)  =  LOG(X)/LOG(B) 

SEC(X)  =  l/COS(X) 

CSC(X)  =  1/SIN(X) 

COT(X)  =  1/TAN(X) 

ARCSIN(X)  =  ATN(X/SQR(1-X*X)) 

ARCCOS(X)  =  1.570796 

-ATN(X/SQR(1-X*X)) 
ARCSEC(X)  =  ATN(SQR(X*X-1)) 

+(X<0)*3. 141593 
ARCCSC(X)  =  ATN(1/SQR(X*X-1)) 

+(X<0)*3. 141593 
ARCCOT(X)  =  1. 57096-  ATN(X) 
SINH(X)  =  (EXP(X)-EXP(-X))/2 
COSH(X)  =  (EXP(X)+EXP(-X))/2 
TANH(X)  =  (EXP(X)-EXP(-X)) 

/(EXP(X)+EXP(-X)) 
SECH(X)  =  2/(EXP(X)+EXP(-X)) 
CSCH(X)  =  2/(EXP(X)-EXP(-X)) 
COTH(X)  =  (EXP(X)+EXP(-X)) 

/(EXP(X)-EXP(-X)) 

ARCSINH(X)  =  LOG(X+SQR(X*X+l)) 

ARCCOSH(X)  =  LOG(X+SQR(X*X-l)) 

ARCTANH(X)  =  LOG((l+X)/(l-X))/2 

ARCSECH(X)  =  LOG((l+SQR(l-X*X))/X) 

ARCCSCH(X)  =  LOG((l+SGN(X)  , 
*SQR(1+X*X))/X) 

ARCCOTH(X)  =  LOG((X+l)/(X-l))/2 
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If  you  use  these  functions,  a  good  way  to  code  them 
would  be  with  the  DEF  FN  statement.  For  example, 
instead  of  coding  the  formula  for  inverse  hyperbolic 
sine  each  time  you  need  it,  you  could  code: 

in  one  place,  then  refer  to  it  as 

FNARCS I NH (Y  J 


each  time  you  need  it. 


Appendix  F.  Communications 


This  appendix  describes  the  BASIC  statements 
required  to  support  RS232  asynchronous 
communication  with  other  computers  and 
peripherals. 


Opening  a  Communications  File 

OPEN  "COM...  allocates  a  buffer  for  I/O  in  the 
same  fashion  as  OPEN  for  diskette  files.  Refer  to 
"OPEN  "COM...  Statement"  in  Chapter  4. 


Communication  I/O 


Since  each  communications  adapter  is  opened  as  a 
file,  all  input/output  statements  that  are  valid  for 
diskette  files  are  valid  for  communications. 

Communications  sequential  input  statements  are 
the  same  as  those  for  diskette  files.  They  are: 

INPUT  # 
LINE  INPUT  # 
INPUTS 

Communications  sequential  output  statements  are 
the  same  as  those  for  diskette  files,  and  are: 

PRINT  # 
PRINT  #  USING 
WRITE  # 

Refer  to  the  INPUT  and  PRINT  sections  for  details 
of  coding  syntax  and  usage. 
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GET  and  PUT  for  Communications  Files 


GET  and  PUT  are  only  slightly  different  for 
communications  files  than  for  diskette  files.  They 
are  used  for  fixed  length  I/O  from  or  to  the 
communications  file.  In  place  of  specifying  the 
record  number  to  be  read  or  written,  you  specify  the 
number  of  bytes  to  be  transferred  into  or  out  of  the 
file  buffer.  This  number  cannot  exceed  the  value  set 
by  the  LEN  option  on  the  OPEN  "COM... 
statement.  Refer  to  the  GET  and  PUT  sections  in 
Chapter  4. 

I/O  Functions 

The  most  difficult  aspect  of  asynchronous 
communication  is  being  able  to  process  characters 
as  fast  as  they  are  received.  At  rates  of  1200  bps  or 
higher,  it  may  be  necessary  to  suspend  character 
transmission  from  the  other  computer  long  enough 
to  "catch  up."  This  can  be  done  by  sending  XOFF 
(CHR$(19))  to  the  other  computer  and  XON 
(CHR$(17))  when  ready  to  resume.  XOFF  tells  the 
other  computer  to  stop  sending,  and  XON  tells  it  it 
can  start  sending  again. 

Note:    This  is  a  commonly  used  convention, 
but  it  is  not  universal.  It  depends  on  the 
protocol  implemented  between  you  and  the 
other  computer  or  peripheral. 

Disk  and  Advanced  BASIC  provide  three  functions 
which  help  in  determining  when  an  "overrun" 
condition  may  occur.  These  are: 

LOC(f)    Returns  the  number  of  characters  in  the 
input  buffer  waiting  to  be  read.  If  the 
number  is  greater  than  255,  LOC  returns 
255. 

LOF(f)    Returns  the  amount  of  free  space  in  the 
input  buffer.  This  is  the  same  as  tf-LOC(f), 
where  n  is  the  size  of  the  communications 
buffer  as  set  by  the  /C:  option  on  the 
BASIC  command.  The  default  for  n  is  256. 


EOF(f)    Returns  true  (-1)  if  the  input  buffer  is 

empty;  false  (0)  if  there  are  any  characters 
waiting  to  be  read. 

Note:    A  "Communication  buffer  overflow" 
can  occur  if  a  read  is  attempted  after  the  input 
buffer  is  full  (that  is,  when  LOF(f)  returns  0). 

INPUT$  Function 

The  INPUT$  function  is  preferred  over  the 
INPUT  #  and  LINE  INPUT  #  statements  when 
reading  communications  files,  since  all  ASCII 
characters  may  be  significant  in  communications. 
INPUT  #  is  least  desirable  because  input  stops  when 
a  comma  (,)  or  carriage  return  is  seen.  LINE 
INPUT  #  stops  when  a  carriage  return  is  seen. 

INPUT$  allows  all  characters  read  to  be  assigned  to 
a  string.  INPUT$(#,/)  will  return  n  characters  from 
the  #/file.  The  following  statements  are  efficient  for 
reading  a  communications  file: 

110  WH I LE  NOT  EOF  (  1  ) 

120  A$=  I  NPUT$  (LOC  ( 1  )  ,-vl) 


(process  data   returned   in  A$) 


190  WEND 

These  statements  return  the  characters  in  the  buffer 
into  A$  and  process  them,  as  long  as  there  are 
characters  in  the  input  buffer.  If  there  are  more  than 
255  characters  in  the  buffer,  only  255  will  be 
returned  at  a  time  to  prevent  "String  overflow." 
Further,  if  this  is  the  case,  EOF(l)  is  false  and  input 
continues  until  the  input  buffer  is  empty.  Simple, 
concise,  and  fast. 


In  order  to  process  characters  quickly,  you  should 
avoid,  if  possible,  examining  every  character  as  you 
receive  it.  If  you  are  looking  for  special  characters 
(such  as  control  characters),  you  can  use  the  INSTR 
function  to  find  them  in  the  input  string. 

An  Example  Program 

The  following  program  enables  the  IBM  Personal 
Computer  to  be  used  as  a  conventional  "dumb" 
terminal  in  a  full  duplex  mode.  This  program 
assumes  a  300  bps  line  and  an  input  buffer  of  256 
bytes  (the  /C:  option  was  not  used  on  the  BASIC 
command). 

10  REM       dumb  terminal  example 

20    'set  screen   to  black  and  white  text  node 

30    1         and  set  width   to  ^0 

'+0  SCREEN  0,0:  Wl  DTH  A0 

50    'turn  off"  soft  key  display;   clear  screen. 
60   '       nake  sure  all    files  are  closed 
70  KEY  OFF:   CLS:  CLOSE 

80    'define  al  I    numeric  variables  as  intecie" 


0 

DEFIMT  A-Z 

00 

'define  true  and  false 

10 

FAL  S  E  =  0 :   TRUE-  NOT  FALSE 

20 

1  de !  i  ne   I  he  XON  ,   XOFF  chai 

'  a  c  t  e  t" 

30 

X0FFS-CHR5  (  19)  :  XONS'-CHRS 

'J  7) 

.  >n 

'ojien  conamun  i  ca  t  i  ons    to  • 

i  1  e  n  i 

50 

1    300   bp-  ,    UEU   pa-'  it/,  7 

Hcit.-. 

A0 

/0 

OPEN   "COM!  :  300  , 1-  ,7"  mS    ■  i 

j-/ 

OF  t  H  "SCKN  :  ' 1   t"CA";   CAT FUT  A ' 

£- 

"j 

/  V 

00 

LCCATF    , ,1 

/"0 

PAt  t:A -FALSE  :    ON   E  E  R  0  R  G  0  T  [ 

j  9000 

'"1  ^ 
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500   'send  keyboard   input  to  com  line 
510   B$=  I  NKEY$  :    IF  B$-  -n"  THEN  PRINT  '-1,6$; 
52.0    'if  no  chars   in   com  buffer,   check  key  in 
530    I F  E0F( 1 }   THEN  5  I  0 

5^0    'if  buffer'  more   than    1/2   full,  then 

550    1       set  PAUSE   flag   to  say   input  suspended, 

560    '        send   XOFF   to  host   to  stop  transmission 

570    IF   LOCO)    128  THEN  PAUSE=TRUE:    PRINT  "l.XOFFS; 

580    'read  contents  ol    com  butter 

590  A$  =  !  NPUT$  I  LOT  f  1  )  ,  ••  1  i 

600    'qet   rid  of   linefeeds   to  avoid  double  space.-. 
610    1       when    input  displayed  on  screen 
62.0   LFP  =  0 

630  LFP=INSTR! LFP+1  ,A$,CHR$(10) j    'look  for  LP 
6^0    IF  LFP  '0  THEN  M I D $ f A$ , L F P , 1 j = "  ":   GOTO  630 
650    'display  com   input,  and   check  for  more 
660   PRINT   "2,A$;:    IF   LOCfl)  -0  THEN  570 
6/0    'if  t ransmii s s i on  suspended  by  XOFF, 
680    '        resume   by   sending  XON 

630    IF  PAUSE   THEN  PAUS  E=FALS  E  :    PRINT     1  ,  XON  $  ; 
700    'check   for   keyboard    input  again 
7 10  GOTO  510 

8599    '  >  '    erro/r,   display  error  number  and  retry 
9000   PRINT    "ERROR  NO.'1;  ERR:  RESUME 

Notes  on  the  Program 

•  "Asynchronous"  communication  implies 
character  I/O  as  opposed  to  line  or  block  I/O. 
Therefore,  all  PRINTs  (either  to 
communications  file  or  to  screen)  are 
terminated  with  a  semicolon  (;).  This  stops  the 
carriage  return  normally  issued  at  the  end  of 
the  list  of  values  to  be  printed. 

•  Line  90,  where  all  numeric  variables  are  defined 
as  integer,  is  coded  because  any  program 
looking  for  speed  optimization  should  use 
integer  counters  in  loops  where  possible. 

•  Note  in  line  5 1 0  that  INKEY$  will  return  a  null 
string  if  no  character  is  pending. 


Operation  of  Control  Signals 


This  section  contains  more  detailed  technical 
information  that  you  may  need  to  know  to 
communicate  with  another  computer  or  peripheral 
from  BASIC. 

The  output  from  the  Asynchronous  Communications 
Adapter  conforms  to  the  EIA  RS2  32-C  standard  for 
interface  between  Data  Terminal  Equipment  (DTE) 
and  Data  Communications  Equipment  (DCE).  This 
standard  defines  a  number  of  control  signals  that  are 
transmitted  or  received  by  your  IBM  Personal 
Computer  to  control  the  interchange  of  data  with 
another  computer  or  peripheral.  These  signals  are 
DC  voltages  that  are  either  ON  (greater  than  +3 
volts)  or  OFF  (less  than  -3  volts).  See  the  IBM 
Persona/  Computer  Technical  Reference  manual  for 
details. 

Control  of  Output  Signals  with  OPEN 

When  you  start  BASIC  on  your  IBM  Personal 
Computer,  the  RTS  (Request  To  Send)  and  DTR 
(Data  Terminal  Ready)  lines  are  held  OFF.  When  an 
OPEN  "COM...  statement  is  performed,  both  of 
these  lines  are  normally  turned  ON.  However,  you 
can  specify  the  RS  option  on  the  OPEN  "COM... 
statement  to  suppress  the  RTS  signal.  The  lines  stay 
ON  until  the  communications  file  is  closed  (by 
CLOSE,  END,  NEW,  RESET,  SYSTEM,  or  RUN 
without  the  R  option).  Even  if  the  OPEN  "COM... 
statement  fails  with  an  error  (as  described  below), 
the  DTR  line  (and  RTS  line,  if  applicable)  is  turned 
ON  and  stays  ON.  This  allows  you  to  retry  the 
OPEN  without  having  to  execute  a  CLOSE. 
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Use  of  Input  Control  Signals 


Normally,  if  either  the  CTS  (Clear  To  Send)  or  DSR 
(Data  Set  Ready)  lines  are  OFF,  then  an  OPEN 
"COM...  statement  will  not  execute.  After  one 
second,  BASIC  will  return  with  a  "Device  Timeout" 
error  (error  code  24).  The  Carrier  Detect 
(sometimes  called  Receive  Line  Signal  Detect)  can 
be  either  ON  or  OFF;  it  has  no  effect  on  the 
operation  of  the  program. 

However,  you  can  specify  how  you  want  these  lines 
tested  with  the  RS,  CS,  DS,  and  CD  options  on  the 
OPEN  "COM...  statement.  Refer  to 
"OPEN  "COM...  Statement"  in  Chapter  4  for  details. 

If  any  of  the  signals  that  are  being  tested  are  turned 
OFF  while  the  program  is  executing,  I/O  statements 
associated  with  the  communications  file  won't 
work.  For  example,  when  you  execute  a  PRINT  # 
statement  after  the  CTS  or  DSR  line  is  turned  off,  a 
"Device  Fault"  (code  25)  or  "Device  Timeout" 
(code  24)  error  occurs.  The  RTS  and  DTR  stay  on 
even  if  such  an  error  occurs. 

You  can  test  for  a  line  disconnect  by  using  the  INP 
function  to  read  the  bits  in  the  MODEM  Status 
Register  on  the  Asynchronous  Communications 
Adapter.  See  the  following  section,  "Testing  for 
Modem  Control  Signals,"  for  details. 


Testing  for  Modem  Control  Signals 

There  are  four  input  control  signals  picked  up  by 
the  Asynchronous  Communications  Adapter.  These 
signals  are  the  CTS  and  DSR  signals  described 
previously,  the  Carrier  Detect  (sometimes  called 
Received  Line  Signal  Detect)  (pin  8),  and  Ring 
Indicator  (pin  22).  You  can  specify  how  you  want  to 
test  the  CTS,  DSR,  and  CD  lines  with  the  OPEN 
"COM...  statement.  Ring  Indicator  is  not  used  at  all 
bv  the  communications  function  in  BASIC. 
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If  you  need  to  test  for  any  of  these  signals  in  a 
program,  you  can  check  the  bits  corresponding  to 
these  signals  in  the  MODEM  Status  Register  on  the 
Asynchronous  Communications  Adapter.  To  read 
the  eight  bits  in  this  register,  you  use  the  INP 
function — use  INP(&H3FE)  to  read  the  register  on 
an  unmodified  communications  adapter,  and 
INP(&H2FE)  to  read  the  register  on  a  modified 
communications  adapter.  See  the  "Asynchronous 
Communications  Adapter"  section  of  the  Technical 
Reference  manual  for  a  description  of  which  bits  in 
the  Status  Register  correspond  to  which  control 
signals.  You  can  also  use  the  Delta  bits  in  this 
register  to  determine  if  transient  signals  have 
appeared  on  any  of  the  control  lines.  Note  that  for  a 
control  signal  to  have  meaning,  the  pin 
corresponding  to  that  signal  must  be  connected  in 
the  cable  to  your  modem  or  to  the  other  computer. 

You  can  also  test  for  bits  in  the  Line  Status  Register 
on  the  Asynchronous  Communications  Adapter. 
Use  INP(&H3FD)  to  access  this  register  on  an 
unmodified  communications  adapter,  and 
INP(&H2FD)  to  access  it  on  a  modified 
communications  adapter.  Again,  the  bits  are 
described  in  the  IBM  Personal  Computer  Technical 
Reference  manual.  These  bits  can  be  used  to 
determine  what  types  of  errors  have  occurred  on 
receipt  of  characters  from  the  communications  line 
or  whether  a  break  signal  has  been  detected. 

Direct  Control  of  Output  Control  Signals 

You  can  control  the  RTS  or  DTR  control  signals 
directly  from  a  BASIC  program  with  an  OUT 
statement.  The  states  (ON  or  OFF)  of  these  signals 
are  controlled  by  bits  in  the  MODEM  Control 
Register  on  the  Asynchronous  Communications 
Adapter.  The  address  of  this  register  is  &H3FC  on  an 
unmodified  communications  adapter  and  &H2FC 
on  a  modified  communications  adapter.  The  IBM 
Personal  Computer  Technical  Reference  manual  describes 
which  of  these  bits  correspond  to  which  signals. 
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You  can  also  modify  bits  in  the  Line  Control 
Register  on  the  Asynchronous  Communications 
Adapter.  You  should  be  careful  in  modifying  these 
bits  as  most  of  the  bits  in  this  register  have  been  set 
by  BASIC  at  the  time  an  OPEN  statement  is 
executed  and  changing  a  bit  could  cause 
communications  failure.  The  Line  Control  Register 
is  at  address  &H3FB  on  an  unmodified 
communications  adapter  and  at  address  &H2  FB  on  a 
modified  communications  adapter. 

When  changing  bits  in  either  the  MODEM  Control 
Register  or  the  Line  Control  Register,  you  should 
first  read  the  register  (with  an  INP  function)  and 
then  rewrite  the  register  with  only  the  pertinent  bit 
or  bits  changed. 

A  bit  you  may  wish  to  control  in  the  Line  Control 
Register  is  bit  6,  the  Set  Break  bit.  This  bit  permits 
you  to  produce  a  Break  signal  on  the 
communications  send  line.  A  Break  is  often  used  to 
signal  a  remote  computer  to  stop  transmission. 
Typically  a  Break  lasts  for  half  a  second.  To  produce 
such  a  signal,  you  must  turn  ON  the  Set  Break,  wait 
for  the  desired  time  of  the  Break  signal,  and  then 
turn  the  bit  OFF.  The  following  BASIC  statements 
will  produce  a  Break  signal  of  approximately  half  a 
second  duration  on  an  unmodified  communications 
adapter. 
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Communication  Errors 

Errors  occur  on  communication  files  in  the 
following  order: 

1)  When  opening  the  file  — 

a)     "Device  Timeout"  if  one  of  the  signals  to 
be  tested  (CTS,  DSR,  or  CD)  is  missing. 

2)  When  reading  data  — 

a)  "Com  buffer  overflow"  if  overrun  occurs. 

b)  "Device  I/O  error"  for  overrun,  break, 
parity,  or  framing  errors. 

c)  "Device  Fault"  if  you  lose  DSR  or  CD. 

3)  When  writing  data  — 

a)  "Device  Fault"  if  you  lose  CTS,  DSR,  or 
CD  on  a  Modem  Status  Interrupt  while 
BASIC  was  doing  something  else. 

b)  "Device  Timeout"  if  you  lose  CTS,  DSR, 
or  CD  while  waiting  to  put  data  in  the 
output  buffer. 
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Appendix  G.  ASCII  Character  Codes 


The  following  table  lists  all  the  ASCII  codes  (in 
decimal)  and  their  associated  characters.  These 
characters  can  be  displayed  using  PRINT  CHR$(^), 
where  n  is  the  ASCII  code.  The  column  headed 
"Control  Character"  lists  the  standard 
interpretations  of  ASCII  codes  0  to  31  (usually  used 
for  control  functions  or  communications). 

Each  of  these  characters  may  be  entered  from  the 
keyboard  by  pressing  and  holding  the  Alt  key,  then 
pressing  the  digits  for  the  ASCII  code  on  the 
numeric  keypad.  Note,  however,  that  some  of  the 
codes  have  special  meaning  to  the  BASIC  program 
editor— the  program  editor  uses  its  own 
interpretation  for  the  codes  and  may  not  display  the 
special  character  listed  here. 
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Acn  i 
AoUl  1 

L-OnirOI 

ASCI  1 

val  ue 

CnsractGr 

value 

Cr 

000 

(null) 

NUL 

032 

<SF 

001 

© 

SOH 

033 

! 

002 

STX 

034 

003 

ETX 

035 

# 

004 

♦ 

EOT 

036 

$ 

005 

ENQ 

037 

0/ 

/o 

006 

* 

ACK 

038 

& 

007 

(beep) 

BEL 

039 

008 

D 

BS 

040 

{ 

009 

(tab) 

HT 

041 

) 

010 

(line  feed) 

LF 

042 

011 

(home) 

VT 

043 

+ 

012 

(form  feed) 

FF 

044 

013 

(carriage  return) 

CR 

045 

- 

014 

SO 

046 

015 

SI 

047 

/ 

016 

DLE 

048 

0 

017 

DC1 

049 

1 

018 

i 

DC2 

050 

2 

019 

j  i 

DC3 

051 

3 

020 

T 

DC4 

052 

4 

021 

r 

3 

IMAK 

053 

5 

022 

SYN 

054 

6 

023 

i 

ETB 

055 

7 

024 

CAN 

056 

8 

025 

i 

EM 

057 

9 

026 

~** 

SUB 

058 

027 

**~ 

ESC 

059 

t 

028 

(cursor  right) 

FS 

060 

< 

029 

(cursor  left) 

GS 

061 

030 

(cursor  up) 

RS 

062 

> 

031 

(cursor  down) 

US 

063 

? 

Character 
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MOl/  1 1 

ASCI  1 

Vsl  U6 

Vsl  IQI  CH*  IC 1 

VdlllB 

Ch 

064 

@ 

096 

065 

A 

097 

a 

066 

B 

098 

b 

067 

C 

099 

c 

068 

D 

100 

d 

069 

E 

101 

e 

070 

F 

102 

f 

071 

G 

103 

g 

072 

H 

104 

h 

073 

1 

105 

i 

074 

J 

106 

j 

075 

K 

107 

k 

076 

L 

108 

I 

077 

M 

109 

m 

078 

N 

110 

n 

079 

0 

1 1 1 

o 

080 

P 

112 

P 

081 

Q 

113 

q 

082 

R 

1 14 

r 

083 

S 

115 

s 

084 

T 

116 

t 

085 

U 

117 

u 

086 

V 

118 

V 

087 

W 

119 

w 

088 

X 

120 

X 

089 

Y 

121 

y 

090 

Z 

122 

z 

091 

r 

[ 

123 

! 

092 

\ 

124 

! 

093 

] 

125 

! 

094 

A 

126 

095 

127 

ASCII 

ASCII 

value 

Character 

value 

Ch; 

128 

Q 

160 

a 

129 

u 

161 

' 

130 

e 

162 

6 

131 

a 

163 

u 

132 

a 

164 

n 

133 

a 

165 

N 

134 

a 

166 

a 

135 

C 

167 

0 

136 

e 

168 

<: 

137 

e 

169 

i — 

138 

e 

170 

— i 

139 

i 

171 

y2 

140 

i 

172 

141 

i 

173 

i 

142 

A 

174 

« 

143 

A 

175 

» 

144 

E 

176 

145 

ae 

177 

146 

AL 

178 

147 

o 

179 

i 

148 

o 

180 

H 

149 

6 

181 

H 

150 

/\ 
u 

182 

Hi 

151 

u 

183 

"Tl 

152 

v 

1 84 

=1 

153 

6 

185 

={| 

154 

u 

186 

II 

155 

187 

=t! 

156 

£ 

188 

=U 

157 

189 

JJ 

158 

Pt 

190 

=1 

159 

/ 

191 

~ 1 

ASCII 

ASCII 

value 

Character 

value 

Character 

192 

L 

224 

a 

193 

_J_ 

225 

194 

~r 

226 

r 

195 

h 

227 

7T 

196 

— 

228 

V 
Li 

197 

4- 

229 

cr 

198 

230 

199 

Ih 

231 

T 

200 

it 

232 

201 

n= 

233 

-e- 

202 

JL 

234 

12 

203 

TT 

235 

6 

204 

Ir 

236 

oo 

205 

237 

0 

206 

_  L 

238 

£ 

207 

— 

239 

n 

208 

240 

= 

209 

241 

+ 

210 

Ti- 

242 

- 

211 

ll- 

243 

212 

>= 

244 

r 

213 

F= 

245 

J 

214 

rr 

246 

-■■ 

215 

4f 

247 

216 

4= 

248 

0 

217 

_j 

249 

• 

218 

r 

250 

• 

219 

■ 

251 

\ 

220 

252 

n 

221 

1 

253 

2 

222 

1 

254 

■ 

223 

255 

(blank  'FF 
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Extended  Codes 


For  certain  keys  or  key  combinations  that  cannot  be 
represented  in  standard  ASCII  code,  an  extended 
code  is  returned  by  the  INKEY$  system  variable.  A 
null  character  (ASCII  code  000)  will  be  returned  as 
the  first  character  of  a  two-character  string.  If  a 
two-character  string  is  received  by  INKEY$,  then 
you  should  go  back  and  examine  the  second 
character  to  determine  the  actual  key  pressed. 
Usually,  but  not  always,  this  second  code  is  the  scan 
code  of  the  primary  key  that  was  pressed.  The  ASCII 
codes  (in  decimal)  for  this  second  character,  and  the 
associated  key(s)  are  listed  on  the  following  page. 
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Second  Code 


Meaning 


3  (null  character)  NUL 

15  (shift  tab)  I  <— 

16-25  Alt-  Q,  W,  E,  R,  T,  Y,  U,  I,  O,  P 

30-38  Alt-  A,  S,  D,  F,  G,  H,  J,  K,  L 

44-50  Alt-  2,  X,  C,  V,  B,  N,  M 

59-68  function  keys  Fl  through  F10 
(when  disabled  as  soft  keys) 

71  Home 

72  Cursor  Up 

73  Pg  Up 

75  Cursor  Left 

77  Cursor  Right 

79  End 

80  Cursor  Down 

81  Pg  Dn 

82  Ins 

83  Del 

84-93  F11-F20  (Shift-  Fl  through  F10) 

94-103  F21-F30  (Ctrl-  Fl  through  FlO) 

104-113  F31-F40  (Alt-  Fl  through  FlO) 

114  Ctrl-PrtSc 

115  Ctrl-Cursor  Left  (Previous  Word) 

1 1 6  Ctrl-Cursor  Right  (Next  Word) 

117  Ctrl- End 

118  Ctrl-PgDn 

119  Ctrl-Home 

120-131  Alt-  1,2,3,4,5,6,7,8,9,0,-  = 

132  Ctrl- PgUp 
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Appendix  H.  Hexadecimal 

Conversion  Table 


n  ex 

Decimal 

rlcX 

Decimal 

1 
1 

1  A 

1  U 

16 

2 

2 

20 

32 

3 

3 

30 

A  O 

48 

4 

A 

4 

A  A 

4U 

64 

5 

c 

5 

c  a 

50 

80 

6 

6 

60 

96 

7 

7 

70 

112 

8 

8 

80 

128 

o 

V 

V 

OA 

90 

1  A  A 
144 

A 

1  a 

AO 

1  A 

1 60 

o 

1  1 

Da 

rSO 

1  "7/" 

1  76 

1  2 

r^A 
L-0 

192 

u 

1 3 

U0 

208 

n 

1  A 
\  4 

TT  A 

ho 

224 

t; 

r 

1  c 

15 

rO 

240 

1  aa 
1  U(J 

it/ 
256 

1000 

4096 

">  a  a 
zUU 

512 

2000 

768 

3000 

1  2288 

4UU 

1024 

4000 

16384 

1  280 

C  AAA 

5000 

20480 

/C  a  a 

1 5  36 

z'  a  a  a 
6000 

24576 

700 

1792 

7000 

28672 

800 

2048 

8000 

32768 

900 

2304 

9000 

36864 

A00 

2560 

A000 

40960 

BOO 

2816 

B000 

45056 

COO 

3072 

Cooo 

49152 

D00 

3328 

DO  00 

5  3248 

E00 

3584 

E000 

57344 

F00 

3840 

F000 

61440 
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endix  I.  Technical  Information 
and  Tips 


This  appendix  contains  more  specific  technical 
information  pertaining  to  BASIC.  Included  are  a 
memory  map,  descriptions  of  how  BASIC  stores 
data  internally,  and  some  special  techniques  you  can 
use  to  improve  program  performance. 

Other  information  may  be  found  in  the  IBM  Personal 
Computer  Technical  Reference  manual. 
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Memory  Map 


The  following  is  a  memory  map  for  Disk  and 
Advanced  BASIC.  DOS  and  the  BASIC  extensions 
are  not  present  for  Cassette  BASIC.  Addresses  are  in 
hexadecimal  in  the  form  segment.offset. 


system 

\ 

□  DS 

S  ?£. 

5.  £ 

O. 

"l 

DOS  workarea 

BASIC 
extensions 


FT 


interpreter 
workarea 


BASIC 
program 


scalar  variables 


string 
space 


BASIC 
stack 


system 
(includes  screen  buffers) 


read-only  memory 


Notes: 

1.  PS  refers  to  DOS 
Program  Segment 

2.  DS  refers  to  BASIC's 
Data  Segment 

3.  the  number  xxxx  is  in 
locations  DS:30  and 
DS:31  (low  byte,  high 
byte) 

4.  the  number  yyyy  is  in 
locations  DS:358, 
DS:359  (low  byte, 
high  byte) 

5.  or  set  by  CLEAR 
command 
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How  Variables  Are  Stored 


Scalar  variables  are  stored  in  BASIC'S  data  area  as 
follows: 


Byte 


AA  /W- 


Q+length 


char 


char 


length 


length  chars 
 VA  /V — 


data 
2,  3, 4,  or  8  bytes 


type 


identifies  the  variable's  type: 


2  integer 

3  string 

4  single-precision 
8  double-precision 


name  is  the  name  of  the  variable.  The  first  two 
characters  of  the  name  are  stored  in  the 
bytes  1  and  2.  Byte  3  tells  how  many  more 
characters  are  in  the  variable  name.  These 
additional  characters  are  stored  starting  at 
byte  4. 

Note  that  this  means  any  variable  name 
will  take  up  at  least  three  bytes.  A  one-  or 
two-character  name  will  occupy  exactly 
three  bytes;  an  x  character  name  will 
occupy  x+1  bytes. 


data         follows  the  name  of  the  variable,  and  may 
be  either  two,  three,  four,  or  eight  bytes 
long  (as  described  by  type).  The  value 
returned  by  the  VARPTR  function  points 
to  this  data. 
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For  string  variables,  data  is  the  string  descriptor: 

•  The  first  byte  of  the  string  descriptor  contains 
the  length  of  the  string  (0  to  255). 

•  The  last  two  bytes  of  the  string  descriptor 
contain  the  address  of  the  string  in  BASIC's 
data  space  (the  offset  into  the  default  segment). 
Addresses  are  stored  with  the  low  byte  first  and 
the  high  byte  second,  so: 

—  The  second  byte  of  the  string  descriptor 
contains  the  low  byte  of  the  offset. 

—  The  third  byte  of  the  string  descriptor 
contains  the  high  byte  of  the  offset. 

For  numeric  variables  data  contains  the  actual  value 
of  the  variable: 

•  Integer  values  are  stored  in  two  bytes,  with  the 
low  byte  first  and  the  high  byte  second. 

•  Single-precision  values  are  stored  in  four  bytes 
in  BASIC's  internal  floating  point  binary 
format. 

•  Double-precision  values  are  stored  in  eight 
bytes  in  BASIC's  internal  floating  point  binary 
format. 

BASIC  File  Control  Block 

When  you  call  VARPTR  with  a  file  number  as  an 
argument,  the  returned  value  is  the  address  of  the 
BASIC  file  control  block.  The  address  is  specified  as 
an  offset  into  BASlCs  Data  Segment.  (Note  that  the 
BASIC  file  control  block  is  not  the  same  as  the  DOS 
file  control  block.) 
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Information  contained  in  the  file  control  block  is  as 
follows  (offsets  are  relative  to  the  value  returned  by 
VARPTR): 

Offset    Length  Description 

0  1         The  mode  in  which  the  file  was 

opened: 


1  - 

Input  only 

2  - 

Output  only 

4.  - 

Random 

16  - 

Append  only 

32  - 

Internal  use 

128  - 

Internal  use 

1  38       DOS  file  control  block 

39  2       For  sequential  files,  the  number 

of  sectors  read  or  written.  For 
random  files,  contains  1  +  the 
last  record  number  read  or 
written. 


41 


42 


Number  of  bytes  in  sector  when 
read  or  written. 

Number  of  bytes  left  in  input 
buffer. 


43 
46 


3  (reserved) 

1       Device  number: 


0,1 

-  Diskette  drives  A:  and  B: 

248  ■ 

■  LPT  3: 

249  ■ 

■  LPT2: 

250  - 

COM2: 

251  ■ 

■  COMl: 

252  - 

■  CAS1: 

253  - 

LPTl: 

254  - 

•  SCRN: 

255  ■ 

■  KYBD: 
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Length  Description 

1       Device  width. 

1       Position  in  buffer  for  PRINT  #. 

1       Internal  use  during  LOAD  and 
SAVE.  Not  used  for  data  files. 

1  Output  position  used  during  tab 
expansion. 

128       Physical  data  buffer.  Used  to 

transfer  data  between  DOS  and 
BASIC.  Use  this  offset  to 
examine  data  in  sequential  I/O 
mode. 

2  Variable  length  record  size. 
Default  is  128.  Set  by  length 
parameter  on  OPEN  statement. 

2       Current  physical  record  number. 

2       Current  logical  record  number. 

1  (reserved) 

2  Diskette  files  only.  Position  for 
PRINT  #,  INPUT  #,  and 
WRITE  #. 

n         Actual  FIELD  data  buffer.  Size  n 
is  determined  by  the  /S:  option 
on  the  BASIC  command.  Use 
this  offset  to  examine  file  data  in 
random  mode. 


Keyboard  Buffer 


Characters  typed  on  the  keyboard  are  saved  in  the 
keyboard  buffer  until  they  are  processed.  Up  to  15 
characters  can  be  held  in  the  buffer;  if  you  try  to 
type  more  than  15  characters,  the  computer  beeps. 

INKEY$  will  read  only  one  character  from  the 
keyboard  buffer  even  if  there  are  several  characters 
pending  there.  INPUT$  can  be  used  to  read 
multiple  characters;  however,  if  the  requested 
number  of  characters  are  not  already  present  in  the 
buffer,  BASIC  will  wait  until  enough  characters  are 
typed. 

The  system  keyboard  buffer  may  be  cleared  by  the 
following  lines  of  code: 

DEF  SEG=0:   POKE  1050,  PEEK( 1 052) 

This  technique  could  be  useful,  for  example,  to 
clear  the  buffer  before  you  ask  the  user  to  "press  any 
key." 

BASIC  has  its  own  line  buffer,  where  the  program 
editor  acts  on  characters  that  are  received  from  the 
system  keyboard  buffer.  BASIC's  line  buffer  maybe 
cleared  using  the  following  code: 

DEF  SEG:   POKE  106,0 


iarch  Order  for 


The  printers  associated  with  LPTl:,  LPT2:,  and 
LPT3:  are  assigned  when  you  switch  your  computer 
on.  The  system  looks  for  printer  adapters  in  a 
particular  sequence;  the  first  printer  adapter  found 
becomes  LPTl:,  the  second  adapter  (if  one  exists) 
becomes  LPT2:,  and  the  third  (if  it  exists)  becomes 
LPT3:.  The  search  order  is  as  follows: 

L     An  IBM  Monochrome  Display  and  Parallel 
Printer  Adapter 

2.  A  Parallel  Printer  Adapter 

3.  A  Parallel  Printer  Adapter  which  has  been 
modified  to  change  its  base  address 


If  a  printer  was  re-routed  using  the  MODE 
command  from  DOS,  the  change  is  effective  in 
BASIC  as  well. 

The  communication  devices  COMl:  and  COM2:  are 
assigned  in  a  manner  similar  to  the  printers.  Their 
search  order  is: 

1.  An  Asynchronous  Communications  Adapter 

2.  A  modified  Asynchronous  Communications 
Adapter 

Switching  Displays 

If  you  have  both  the  Color/Graphics  Monitor 
Adapter  and  the  IBM  Monochrome  Display  and 
Parallel  Printer  Adapter  in  your  IBM  Personal 
Computer,  the  one  BASIC  will  normally  write  to 
would  be  the  Monochrome  Display.  However,  you 
can  switch  from  one  display  to  the  other  from 
BASIC  by  using  the  following  code: 

10   1   switch  to  monochrome  adapter 
20  DEF  S EG  =  0 

30  POKE   &H^10,    (PEEK(&H^10)   OR  &H30) 

^0  SCREEN  0 

50  W  I  DTH  ^40 

60  W I DTH  80 

70  LOCATE  ,,1,12,13 

10  1   switch  to  color  adapter 

20  DEF  SEG  =  0 

30  POKE  &rUt10,    (PEEK(8H^10)    AND  &HCF)    OR  &H  1  0 

'»0  SCREEN  1,0,0,0 

50  SCREEN  0 

60  Wl DTH  ^0 

70  LOCATE   , , 1 ,6,7 

Note:    When  you  use  this  technique,  the 
screen  you  are  switching  to  is  cleared.  Also,  you 
may  need  to  keep  track  of  the  cursor  location 
independently  for  each  display. 
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Some  Techniques  with  Color 


Sixteen  Background  Colors:  In  text  mode,  if  you 
are  willing  to  give  up  blink,  you  can  get  all  16  colors 
(0-15)  for  the  background  color.  Do  the  following: 

In  40- column  width:      OUT  5H3D8,8 

In  80-column  width:  0UT&H3D8,9 

Character  Color  in  Graphics  Mode:  You  can  display 
regular  text  characters  while  in  graphics  mode.  However, 
if  you  are  not  using  a  U.S.  keyboard,  refer  to 
"GRAFTABL-Color/Graphics  Adapter  Characters"  in 
the  DOS  section  of  the  Guide  to  Operations. 

In  medium  resolution,  the  foreground  color  of  the 
characters  is  color  number  3;  the  background  is  color 
number  0. 

You  can  change  the  foreground  color  of  the 
characters  from  3  to  2  or  1  by  performing  a: 

DEF  S EG :  POKE  &HhE  ,  color 

where  color  is  the  desired  foreground  color  (1,  2,  or 
3 —  0  is  not  allowed).  Later  PRINTs  will  use  the 
specified  foreground  color. 


s  and  Techniques 


Often  there  are  several  different  ways  you  can  code 
something  in  BASIC  and  still  get  the  same  function. 
This  section  contains  some  general  hints  for  coding 
to  improve  program  performance. 

GENERAL 

•  Combine  statements  where  convenient  to 
take  advantage  of  the  255  character  statement 
length.  For  example: 

Do 

100  FOR   1=1   TO   10:   READ  A(l):   NEXT  I 
Instead  of 

100  FOR   1=1   TO  10 
1 10  READ  A ( I ) 
120  NEXT  ! 

•  Avoid  repetitive  evaluation  of  expressions.  If 

you  do  the  identical  calculation  in  several 
statements,  you  can  evaluate  the  expression 
once  and  save  the  result  in  a  variable  for  use  in 
later  statements.  For  example: 

Do  Instead  of 

300  X=C-3+D  310  A=C--3+D+Y 

310  A=X+Y  320  B  =  C--'"3+D+Z 

320  B=X+Z 

However,  assigning  a  constant  to  a  variable  is 
faster  than  assigning  the  value  of  another 
variable  to  the  variable. 


Use  simple  arithmetic.    In  general,  addition 
is  performed  faster  than  multiplication,  and 
multiplication  is  faster  than  division  or 
exponentiation. 

Consider  these  example: 

2  50  B=A*.5  2  30  B  =  A/2 

500  B=A+A  500  B  =  A*2 

650  3  A '  A*  A-  650  B  <v"  3 

750  b/=A/  h  750  B^=INT(A/A) 

Use  built-in  functions.    Use  the  built-in 
system  functions  where  possible;  they  always 
execute  faster  than  the  same  capability  written 
in  BASIC. 

Use  remarks  sparingly.    It  takes  a  small 
amount  of  time  for  BASIC  to  identify  a  remark. 
Use  the  single  quote  (')  to  place  remarks  at  the 
end  of  the  line  rather  than  using  a  separate 
statement  for  them  when  possible.  This 
improves  performance  and  saves  storage  by 
eliminating  the  need  for  a  line  number.  For 
example: 

Do 

10    FOR   1=1   TO  10 

20  A( ! ) =30    1    initialize  A 

30  NEXT  I 

Instead  of 

10  FOR   (=1  TO  10 
15   '    initial i  ze  A 
20  A( I ) =30 
30  NEXT  I 

Just  a  note  about  IBM  Personal  .Cnmmit£j;^,_v 
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where  in  memory  that  line  is.  Therefore  BASIC 
has  to  search  through  the  line  numbers  in  the 
program,  starting  at  the  beginning,  to  find  the 
line  it's  looking  for. 

In  some  other  BASICs,  this  search  must  be 
performed  each  time  the  branch  occurs  in  the 
program.  In  IBM  Personal  Computer  BASIC, 
the  search  is  only  performed  once,  and 
thereafter  the  branch  is  direct.  So  placing 
frequently-used  subroutines  at  the  beginning 
of  the  program  will  not  make  your  program  run 
faster. 

LOGIC  CONTROL 

•  Use  the  capabilities  of  the  IF  statement.  By 

using  AND  and  OR  and  the  ELSE  clause,  you 
can  often  avoid  the  need  for  more  IF 
statements  and  additional  code  in  the  program. 
For  example: 

Do 

2021    IF  A=B  AND  C=D  THEN  Z=  1 2  ELSE  Z=B 
Instead  of 

im   \  F  A=B  THEN  GOTO  210 

205  GOTO  215 

2H.5   IF  C=D  THEN  225 

21.;,  Z  =  B 

220  GOTO  230 

225  Z=12 

2  3t,;  .  .  . 

•  Order  IF  statements  so  the  most  frequently 
occurring  condition  is  tested  first.  This  avoids 
having  to  make  extra  tests.  For  example, 
suppose  you  have  a  data  entry  file  for  customer 
orders  which  consists  of  different  record  types 
and  numerous  individual  transactions. 


A  typical  record  group  looks  like  this: 
Type  code        Record  type 
A  Header 

B  Customer  name  and  address 

C  Transaction 
C  Transaction 


C  Transaction 
D  Trailer 

Do 

100  I F  TYPE$="C"  THEN  3000 

110  IF  TYPE$-"A"  THEN  1 

1 20  IF  TYPE$="B"  THEN  2( 

1 30  IF  TYPE$="D"  THEN  4000 

Instead  of 

100  IF  TYPE$="A"  THEN  1000 

110  IF  TYPE$="B"  THEN  2000 

120  IF  TYPE$="C"  THEN  3000 

1 30  IF  TYPE$="D"  THEN  4000 

If  you  had  100  groups,  with  10  transactions  per 
group,  moving  the  test  to  the  beginning  of  the 
list  results  in  1800  fewer  IF  statements  being 
executed. 


Another  example  of  ordering  IF  statements  in  a 
cascade  so  less  tests  need  to  be  performed: 

DO 

200  IF  A<>1  THEN  250 

210  IF  B=1  THEN  X=0 

220  IF  B=2  THEN  X=1 

230  IF  B=3  THEN  X=2 

2*+0  GOTO  280 

250  IF  B=1  THEN  X=3 

260  IF  B=2  THEN  X=k 

270  IF  B=3  THEN  X=5 

280  ... 

Instead  of 

200  IF  A=1   AND  B= 1   THEN  X=0 

210  IF  A=1   AND  B=2  THEN  X= 1 

220  IF  A=1   AND  B=3  THEN  X=2 

230  IF  A<>1   AND  B=l   THEN  X=3 

2A0  IF  A'->1  AMD  B=2  THEN  X=^ 

250  IF  A<>1   AND  B=3  THEN  X=5 

LOOPS 

•  Use  integer  counters  on  FOR... NEXT  loops 
when  possible.  Integer  arithmetic  is  performed 
faster  than  single-  and  double-precision 
arithmetic. 

•  Omit  the  variable  on  the  NEXT  statement 
where  possible.  If  you  include  the  variable, 
BASIC  takes  a  little  time  to  check  to  see  that  it 
is  correct.  It  may  be  necessary  to  include  the 
variable  on  the  NEXT  statement  if  you  are 
branching  out  of  nested  loops.  Refer  to  "FOR 
and  NEXT  Statements"  in  Chapter  4  for  more 
information. 

•  Use  FOR.. .NEXT  loops  instead  of  using  the  IF, 
GOTO  combination  of  statements. 


For  example: 
Do 

200  FOR  1=1  TO  10 
300  NEXT  I 


Instead  of 

200  1=1 
210  ... 


290  1=1+1 

300   IF    I- = 1 0  THEN  210 


•     Remove  unnecessary  code  from  loops.  This 
includes  statements  which  don't  affect  the 
loop,  as  well  as  non-executable  statements  such 
as  REM  and  DATA.  For  example: 


Do 


10  A=B+1 

20  FOR  X=1  TO  100 

30   IF  D(X)  -A  THEN  D(X)=A 

^0  NEXT  X 


Instead  of 


10  FOR  X=1  TO  100 

20  A=B+1 

30  IF  D(X)   A  THEN  D(X)=A 

^0  NEXT  X 


In  the  preceding  example,  it  is  not  necessary  to 
calculate  the  value  of  A  each  time  through  the 
loop,  because  the  loop  never  changes  the  value 
of  A. 

The  next  example  shows  a  non-executable 
statement. 


Do 

200  DATA  5,  12,  1 9^3 
210  FOR   1=1  TO  100 

300  NEXT  I 


Instead  of 

200   FOR   l=l   TO  100 
210  DATA  5,    12,  19^3 

300  NEXT  I 
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Appendix  J.  Glossary 


This  part  of  the  book  explains  many  of  the  technical 
terms  you  may  run  across  while  programming  in 
BASIC. 

absolute  coordinate  form:  In  graphics,  specifying 
the  location  of  a  point  with  respect  to  the  origin  of 
the  coordinate  system. 

access  mode:    A  technique  used  to  obtain  a  specific 
logical  record  from,  or  put  a  logical  record  into,  a 
file. 


accuracy:  The  quality  of  being  free  from  error.  On 
a  machine  this  is  actually  measured,  and  refers  to  the 
size  of  the  error  between  the  actual  number  and  its 
value  as  stored  in  the  machine. 


active  page:    On  the  Color/Graphics  Monitor 
Adapter,  the  screen  buffer  which  has  information 
written  to  it.  It  may  be  different  from  the  screen 
buffer  whose  information  is  being  displayed. 

adapter:    A  mechanism  for  attaching  parts. 

address:    The  location  of  a  register,  a  particular 
part  of  memory,  or  some  other  data  source  or 
destination.  Or,  to  refer  to  a  device  or  a  data  item  by 
its  address. 


addressable  point:    In  computer  graphics,  any 
point  in  a  display  space  that  can  be  addressed.  Such 
points  are  finite  in  number  and  form  a  discrete  grid 
over  the  display  space. 

algorithm:  A  finite  set  of  well-defined  rules  for  the 
solution  of  a  problem  in  a  finite  number  of  steps. 
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allocate:  To  assign  a  resource,  such  as  a  diskette 
file  or  a  part  of  memory,  to  a  specific  task. 

alphabetic  character.    A  letter  of  the  alphabet. 

alphameric  or  alphanumeric:    Pertaining  to  a 
character  set  that  contains  letters  and  digits. 

application  program:    A  program  written  by  or  for 
a  user  which  applies  to  the  user's  work.  For 
example,  a  payroll  application  program. 

argument:    A  value  that  is  passed  from  a  calling 
program  to  a  function. 

arithmetic  overflow:    Same  as  overflow. 

array:  An  arrangement  of  elements  in  one  or  more 
dimensions. 

ASCII:    American  National  Standard  Code  for 
Information  Interchange.  The  standard  code  used 
for  exchanging  information  among  data  processing 
systems  and  associated  equipment.  An  ASCII  file  is  a 
text  file  where  the  characters  are  represented  in 
ASCII  codes. 

asynchronous:    Without  regular  time  relationship; 
unpredictable  with  respect  to  the  execution  of  a 
program's  instructions. 

attribute:  A  property  or  characteristic  of  one  or 
more  items. 

background:    The  area  which  surrounds  the 
subject.  In  particular,  the  part  of  the  display  screen 
surrounding  a  character. 

backup:    Pertaining  to  a  system,  device,  file,  or 
facility  that  can  be  used  in  case  of  a  malfunction  or 
loss  of  data. 


baud:    A  unit  of  signalling  speed  equal  to  the 
number  of  discrete  conditions  or  signal  events  per 
second. 

binary:    Pertaining  to  a  condition  that  has  two 
possible  values  or  states.  Also,  refers  to  the  Base  2 
numbering  system. 

bit:    A  binary  digit. 

blank:    A  part  of  a  data  medium  in  which  no 
characters  are  recorded.  Also,  the  space  character. 

blinking:    An  intentional  regular  change  in  the 
intensity  of  a  character  on  the  screen. 

boolean  value:  A  numeric  value  that  is  interpreted 
as  "true"  (if  it  is  not  zero)  or  "false"  (if  it  is  zero). 

bootstrap:    An  existing  version,  perhaps  a 
primitive  version,  of  a  computer  program  that  is 
used  to  establish  another  version  of  the  program. 
Can  be  thought  of  as  a  program  which  loads  itself. 

bps:    Bits  per  second. 

bubble  sort:    A  technique  for  sorting  a  list  of  items 
into  sequence.  Pairs  of  items  are  examined,  and 
exchanged  if  they  are  out  of  sequence.  This  process 
is  repeated  until  the  list  is  sorted. 

buffer:  An  area  of  storage  which  is  used  to 
compensate  for  a  difference  in  rate  of  flow  of  data, 
or  time  of  occurrence  of  events,  when  transferring 
data  from  one  device  to  another.  Usually  refers  to  an 
area  reserved  for  I/O  operations,  into  which  data  is 
read  or  from  which  data  is  written. 

bug:    An  error  in  a  program. 

byte:  The  representation  of  a  character  in  binary. 
Eight  bits. 


call:    To  bring  a  computer  program,  a  routine,  or  a 
subroutine  into  effect,  usually  by  specifying  the 
entry  conditions  and  jumping  to  an  entry  point. 

carriage  return  character  (CR):    A  character  that 
causes  the  print  or  display  position  to  move  to  the 
first  position  on  the  same  line. 

channel:  A  path  along  which  signals  can  be  sent, 
for  example,  a  data  channel  or  an  output  channel. 

character:    A  letter,  digit,  or  other  symbol  that  is 
used  as  part  of  the  organization,  control,  or 
representation  of  data.  A  connected  sequence  of 
characters  is  called  a  character  string. 

clock:  A  device  that  generates  periodic  signals 
used  for  synchronization.  Each  signal  is  called  a 
clock  pulse  or  clock  tick. 

code:  To  represent  data  or  a  computer  program  in  a 
symbolic  form  that  can  be  accepted  by  a  computer; 
to  write  a  routine.  Also,  loosely,  one  or  more 
computer  programs,  or  part  of  a  program. 

comment:    A  statement  used  to  document  a 
program.  Comments  include  information  that  may 
be  helpful  in  running  the  program  or  reviewing  the 
output  listing. 

communication:  The  transmission  and  reception 
of  data. 

complement:    An  "opposite."  In  particular,  a 
number  that  can  be  derived  from  a  given  number  by 
subtracting  it  from  another  given  number. 

compression:    Arranging  data  so  it  takes  up  a 
minimal  amount  of  space. 


concatenation:    The  operation  that  joins  two 
strings  together  in  the  order  specified,  forming  a 
single  string  with  a  length  equal  to  the  sum  of  the 
lengths  of  the  two  strings. 

constant:    A  fixed  value  or  data  item. 

control  character:  A  character  whose  occurrence 
in  a  particular  context  initiates,  modifies,  or  stops  a 
control  operation.  A  control  operation  is  an  action 
that  affects  the  recording,  processing,  transmission, 
or  interpretation  of  data;  for  example,  carriage 
return,  font  change,  or  end  of  transmission. 

coordinates:    Numbers  which  identify  a  location 
on  the  display. 

cursor:  A  movable  marker  that  is  used  to  indicate  a 
position  on  the  display. 

debug:    To  find  and  eliminate  mistakes  in  a 
program. 

default:    A  value  or  option  that  is  assumed  when 
none  is  specified. 

delimiter:    A  character  that  groups  or  separates 
words  or  values  in  a  line  of  input. 

diagnostic:    Pertaining  to  the  detection  and 
isolation  of  a  malfunction  or  mistake. 

directory:  A  table  of  identifiers  and  references  to 
the  corresponding  items  of  data.  For  example,  the 
directory  for  a  diskette  contains  the  names  of  files 
on  the  diskette  (identifiers),  along  with  information 
that  tells  DOS  where  to  find  the  file  on  the  diskette. 

disabled:  A  state  that  prevents  the  occurrence  of 
certain  types  of  interruptions. 


DOS:  Disk  Operating  System.  In  this  book,  refers 
only  to  the  IBM  Personal  Computer  Disk  Operating 
System. 

dummy:    Having  the  appearance  of  a  specified 
thing  but  not  having  the  capacity  to  function  as 
such.  For  example,  a  dummy  argument  to  a 
function. 

duplex:    In  data  communication,  pertaining  to  a 
simultaneous  two-way  independent  transmission  in 
both  directions.  Same  as  full  duplex. 

dynamic:    Occurring  at  the  time  of  execution. 

echo:    To  reflect  received  data  to  the  sender.  For 
example,  keys  pressed  on  the  keyboard  are  usually 
echoed  as  characters  displayed  on  the  screen. 

edit:    To  enter,  modify,  or  delete  data. 

element:  A  member  of  a  set;  in  particular,  an  item 
in  an  array. 

enabled:  A  state  of  the  processing  unit  that  allows 
certain  types  of  interruptions. 

end  of  file  (EOF):    A  "marker"  immediately 
following  the  last  record  of  a  file,  signalling  the  end 
of  that  file. 

event:    An  occurrence  or  happening;  in  IBM 
Personal  Computer  Advanced  BASIC,  refers 
particularly  to  the  events  tested  by  the  COM(n), 
KEY(n),  PEN,  and  STRIG(n). 

execute:  To  perform  an  instruction  or  a  computer 
program. 

extent:    A  continuous  space  on  a  diskette, 
occupied  or  reserved  for  a  particular  file. 


initialize:  To  set  counters,  switches,  addresses,  or 
contents  of  memory  to  zero  or  other  starting  values 
at  the  beginning  of,  or  at  prescribed  points  in,  the 
operation  of  a  computer  routine. 

instruction:    In  a  programming  language,  any 
meaningful  expression  that  specifies  one  operation 
and  its  operands,  if  any. 

integer:    One  of  the  numbers  0,  ±1,  ±2,  ±3,  ... 

integrity:    Preservation  of  data  for  its  intended 
purpose;  data  integrity  exists  as  long  as  accidental  or 
malicious  destruction,  alteration,  or  loss  of  data  are 
prevented. 

interface:    A  shared  boundary. 

interpret:    To  translate  and  execute  each  source 
language  statement  of  a  computer  program  before 
translating  and  executing  the  next  statement. 

interrupt:    To  stop  a  process  in  such  a  way  that 
it  can  be  resumed. 

invoke:  To  activate  a  procedure  at  one  of  its  entry 
points. 

joystick:  A  lever  that  can  pivot  in  all  directions  and 
is  used  as  a  locator  device. 

justify:    To  align  characters  horizontally  or 
vertically  to  fit  the  positioning  constraints  of  a 
required  format. 

K:  When  referring  to  memory  capacity,  two  to  the 
tenth  power  or  1024  in  decimal  notation. 

keyword:    One  of  the  predefined  words  of  a 
programming  language;  a  reserved  word. 

leading:  The  first  part  of  something.  For  example, 
you  might  refer  to  leading  zeroes  or  leading  blanks 
in  a  character  string. 


function  key:    One  of  the  ten  keys  labeled  Fl 
through  F10  on  the  left  side  of  the  keyboard. 

garbage  collection:    Synonym  for  housecleaning. 

graphic:  A  symbol  produced  by  a  process  such  as 
handwriting,  printing,  or  drawing. 

half  duplex:    In  data  communication,  pertaining 
to  an  alternate,  one  way  at  a  time,  independent 
transmission. 

hard  copy:  A  printed  copy  of  machine  output  in  a 
visually  readable  form. 

header  record:    A  record  containing  common, 
constant,  or  identifying  information  for  a  group  of 
records  that  follows. 

hertz  (Hz):  A  unit  of  frequency  equal  to  one  cycle 
per  second. 

hierarchy:    A  structure  having  several  levels, 
arranged  in  a  tree-like  form.  "Hierarchy  of 
operations"  refers  to  the  relative  priority  assigned 
to  arithmetic  or  logical  operations  which  must  be 
performed. 

host:    The  primary  or  controlling  computer  in  a 
multiple  computer  installation. 

housecleaning:    When  BASIC  compresses  string 
space  by  collecting  all  of  its  useful  data  and  frees  up 
unused  areas  of  memory  that  were  once  used  for 
strings. 

implicit  declaration:  The  establishment  of  a 
dimension  for  an  array  without  it  having  been 
explicitly  declared  in  a  DIM  statement. 


increment:    A  value  used  to  alter  a  counter. 


matrix:    An  array  with  two  or  more  dimensions. 


matrix  printer:  A  printer  in  which  each  character 
is  represented  by  a  pattern  of  dots. 

menu:    A  list  of  available  operations.  You  select 
which  operation  you  want  from  the  list. 

minifloppy:    A  5-1/4  inch  diskette. 

nest:    To  incorporate  a  structure  of  some  kind  into 
another  structure  of  the  same  kind.  For  example, 
you  can  nest  loops  within  other  loops,  or  call 
subroutines  from  other  subroutines. 

notation:  A  set  of  symbols,  and  the  rules  for  their 
use,  for  the  representation  of  data. 

null:  Empty,  having  no  meaning.  In  particular,  a 
string  with  no  characters  in  it. 

octal:    Pertaining  to  a  Base  8  number  system. 

offset:    The  number  of  units  from  a  starting  point 
(in  a  record,  control  block,  or  memory)  to  some 
other  point.  For  example,  in  BASIC  the  actual 
address  of  a  memory  location  is  given  as  an  offset  in 
bytes  from  the  location  defined  by  the  DEF  SEG 
statement. 

on-condition:    An  occurrence  that  could  cause  a 
program  interruption.  It  may  be  the  detection  of  an 
unexpected  error,  or  of  an  occurrence  that  is 
expected,  but  at  an  unpredictable  time. 

operand:    That  which  is  operated  upon. 
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light  pen:  A  light  sensitive  device  that  is  used  to 
select  a  location  on  the  display  by  pointing  it  at  the 
screen. 

line:  When  referring  to  text  on  a  screen  or  printer, 
one  or  more  characters  output  before  a  return  to  the 
first  print  or  display  position.  When  referring  to 
input,  a  string  of  characters  accepted  by  the  system 
as  a  single  block  of  input;  for  example,  all  characters 
entered  before  you  press  the  Enter  key.  In  graphics, 
a  series  of  points  drawn  on  the  screen  to  form  a 
straight  line.  In  data  communications,  any  phvsical 

line  feed  (LF):    A  character  that  causes  the  print  or 
display  position  to  move  to  the  corresponding 
position  on  the  next  line. 

literal:    An  explicit  representation  of  a  value, 
especially  a  string  value;  a  constant. 

location:    Any  place  in  which  data  may  be  stored. 

loop:  A  set  of  instructions  that  may  be  executed 
repeatedly  while  a  certain  condition  is  true. 

M:    Mega;  one  million.  When  referring  to  memory, 
two  to  the  twentieth  power;  1,048,576  in  decimal 
notation. 

machine  infinity:  The  largest  number  that  can  be 
represented  in  a  computer's  internal  format. 

mantissa:    For  a  number  expressed  in  floating 
point  notation,  the  numeral  that  is  not  the 
exponent. 

mask:    A  pattern  of  characters  that  is  used  to 
control  the  retention  or  elimination  of  another 
pattern  of  characters. 


precision:  A  measure  of  the  ability  to  distinguish 
between  nearly  equal  values. 

prompt:    A  question  the  computer  asks  when  it 
needs  you  to  supply  information. 

protect:  To  restrict  access  to  or  use  of  all,  or  part 
of,  a  data  processing  system. 

queue:    A  line  or  list  of  items  waiting  for  service; 
the  first  item  that  went  in  the  queue  is  the  first  item 
to  be  serviced. 

random  access  memory:  Storage  in  which  you  can 
read  and  write  to  any  desired  location.  Sometimes 
called  direct  access  storage. 

range:  The  set  of  values  that  a  quantity  or  function 
may  take. 

raster  scan:    A  technique  of  generating  a  display 
image  by  a  line-by-line  sweep  across  the  entire 
display  screen.  This  is  the  way  pictures  are  created 
on  a  television  screen. 

read-only:  A  type  of  access  to  data  that  allows  it  to 
be  read  but  not  modified. 

record:    A  collection  of  related  information, 
treated  as  a  unit.  For  example,  in  stock  control,  each 
invoice  might  be  one  record. 

recursive:    Pertaining  to  a  process  in  which  each 
step  makes  use  of  the  results  of  earlier  steps,  such  as 
when  a  function  calls  itself. 


relative  coordinates:    In  graphics,  values  that 
identify  the  location  of  a  point  by  specifying 
displacements  from  some  other  point. 

reserved  word:    A  word  that  is  defined  in  BASIC  for 
a  special  purpose,  and  that  you  cannot  use  as  a 
variable  name. 
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operating  system:    Software  that  controls  the 
execution  of  programs;  often  used  to  refer  to  DOS. 

operation:    A  well-defined  action  that,  when 
applied  to  any  permissible  combination  of  known 
entities,  produces  a  new  entity. 

overflow:    When  the  result  of  an  operation 
exceeds  the  capaci  ty  of  the  intended  unit  of  storage. 

overlay:    To  use  the  same  areas  of  memory  for 
different  parts  of  a  computer  program  at  different 
times. 

overwrite:  To  record  into  an  area  of  storage  so  as 
to  destroy  the  data  that  was  previously  stored  there. 

pad:  To  fill  a  block  with  dummy  data,  usually  zeros 
or  blanks. 

page:    Part  of  the  screen  buffer  that  can  be 
displayed  and/or  written  on  independently. 

parameter:  A  name  in  a  procedure  that  is  used  to 
refer  to  an  argument  passed  to  that  procedure. 

parity  check:    A  technique  for  testing  transmitted 
data.  Typically,  a  binary  digit  is  appended  to  a  group 
of  binary  digits  to  make  the  sum  of  all  the  digits 
either  always  even  (even  parity)  or  always  odd  (odd 
party). 

pixel:    A  graphics  "point."  Also,  the  bits  which 
contain  the  information  for  that  point. 

port:    An  access  point  for  data  entry  or  exit. 

position:    In  a  string,  each  location  that  may  be 
occupied  by  a  character  and  that  may  be  identified 
by  a  number. 


storage:    A  device,  or  part  of  a  device,  that  can 
retain  data.  Memory. 

string:    A  sequence  of  characters. 

subscript:  A  number  that  identifies  the  position  of 
an  element  in  an  array. 

syntax:    The  rules  governing  the  structure  of  a 
language. 

table:    An  arrangement  of  data  in  rows  and 
columns. 

target:    In  an  assignment  statement,  the  variable 
whose  value  is  being  set. 

telecommunication:    Synonym  for  data 
communication. 

terminal:  A  device,  usually  equipped  with  a 
keyboard  and  display,  capable  of  sending  and 
receiving  information. 

toggle:    Pertaining  to  anything  having  two  stable 
states;  to  switch  back  and  forth  between  the  two 
states. 

trailing:    Located  at  the  end  of  a  string  or  number. 
For  example,  the  number  1000  has  three  trailing 
zeros. 

trap:  A  set  of  conditions  that  describe  an  event  to 
be  intercepted  and  the  action  to  be  taken  after  the 
interception. 

truncate:  To  remove  the  ending  elements  from  a 
string. 

two's  complement:    A  form  for  representing 
negative  numbers  in  the  binary  number  system. 
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resolution:    In  computer  graphics,  a  measure  of 
the  sharpness  of  an  image,  expressed  as  the  number 
of  lines  per  unit  of  length  discernible  in  that  area. 

routine:    Part  of  a  program,  or  a  sequence  of 
instructions  called  by  a  program,  that  may  have 
some  general  or  frequent  use. 

row:    A  horizontal  arrangement  of  characters  or 
other  expressions. 

scalar:    A  value  or  variable  that  is  not  an  array. 

scale:    To  change  the  representation  of  a  quantity, 
expressing  it  in  other  units,  so  that  its  range  is 
brought  within  a  specified  range. 

scan:    To  examine  sequentially,  part  by  part.  See 
raster  scan. 

scroll:    To  move  all  or  part  of  the  display  image 
vertically  or  horizontally  so  that  new  data  appears  at 
one  edge  as  old  data  disappears  at  the  opposite  edge. 

segment:    A  particular  64K-byte  area  of  memory. 

sequential  access:    An  access  mode  in  which 
records  are  retrieved  in  the  same  order  in  which  they 
were  written.  Each  successive  access  to  the  file  refers 
to  the  next  record  in  the  file. 

stack:    A  method  of  temporarily  storing  data  so 
that  the  last  item  stored  is  the  first  item  to  be 
processed. 

statement:    A  meaningful  expression  that  may 
describe  or  specify  operations  and  is  complete  in  the 
context  of  the  BASIC  programming  language. 

stop  bit:    A  signal  following  a  character  or  block 
that  prepares  the  receiving  device  to  receive  the 
next  character  or  block. 
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typematic  key:  A  key  that  repeats  as  long  as  you 
hold  it  down. 

update:    To  modify,  usually  a  master  file,  with 
current  information. 

variable:  A  quantity  that  can  assume  any  of  a  given 
set  of  values. 

variable-length  record:    A  record  having  a  length 
independent  of  the  length  of  other  records  in  the 
file. 

vector:    In  graphics,  a  directed  line  segment.  More 
generally,  an  ordered  set  of  numbers,  and  so,  a 
one-dimensional  array. 

wraparound:  The  technique  for  displaying  items 
whose  coordinates  lie  outside  the  display  area. 

write:  To  record  data  in  a  storage  device  or  on  a 
data  medium. 


hexadecimal    4-115,  H-l 
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position  of  4-15  3 

size  4-158 
FILES  4-97 
FIX  4-99 
fixed  point  3-9 
fixed-length  strings  4-163 
floating  point  3-9 
floor  function  4-130 
flushing  the  keyboard 

buffer  1-7 
folding,  line  2-27 
FOR   4-100,  1-14 
foreground    3-40,  4-49 
format  notation  v 
formatting  4-219 
FRE  4-104 

free  space    2-5,  4-44,  4-104 
frequency  table  4-263 
function  keys  2-9 
functions    3-29,  3-32,  4-5, 
4-17,  1-11 

derived    Appendix  E 

user-defined  4-68 


G 

garbage  collection  4-104 
GET  (files)  4-106,  B-10 
GET  (graphics)  4-108 
glissando  4-264 
GOSUB  4-111,4-180 
GOTO  4-113,4-180 
graphics    3-38,  D-l 
graphics  modes    3-41,  4-257 


graphics  statements 
CIRCLE  4-41 
COLOR  4-54 
DRAW  4-79 
GET  4-108 
LINE  4-141 
PAINT  4-203 
POINT  function  4-213 
PSET  and  PRESET  4-228 
PUT    4-2  32 


H 

hard  copy  of  screen  2-13 
HEX$  4-115 
hexadecimal  3-10,4-115, 
H-l 

hierarchy  of  operations  3-29 
high  resolution  3-43,  4-257 
high-intensity 

characters    4-50,  4-51 
hold  2-17 
Home  key  2-20 
housecleaning  4-104 

I 

I/O  statements  4-13, 

Appendix  B 
IF   4-116,  D-2,  1-12 
IMP  3-25 
implication  3-25 
implicit  declaration  of 

arrays  3-17 
index  (position  in  string) 

4-129 
indirect  mode  2-7 
initializing  BASIC  2-3 
INKEY$    4-119,  G-6 
INP  4-121 
INPUT  4-122 
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E 

EDIT    3-3,  4-84 
editor  2-19 
editor  keys  2-19 

Backspace  2-28 

Ctrl-Break  2-29 

Ctrl-End  2-25 

Ctrl-Home  2-20 

Cursor  Down  2-21 

Cursor  Left  2-22 

Cursor  Right  2-22 

Cursor  Up  2-21 

Del  2-27 

End  2-25 

Esc  2-28 

Home  2-20 

Ins  2-26 

Next  Word  2-23 

Previous  Word  2-24 

Tab  2-30 
ELSE  4-116 
END  4-85 
End  key  2-25 
end  of  file    4-86,  B-7 
ending  BASIC  4-278 
Enter  key  2-11 
entering  BASIC 
program  2-36 
entering  data  2-19 
EOF    4-86,  B-7 
equivalence  3-25 
EQV  3-25 
ERASE  4-87 
ERASE  (DOS)  4-136 
erasing  a  file    4-1 36 
erasing  a  program  2-38, 

4-174 
erasing  arrays  4-87 
erasing  characters  2-33 
erasing  part  of  a  line  2-35 
erasing  program  lines  2-37, 
4-76 


erasing  variables  4-44 

ERL  4-89 

ERR  4-89 

ERROR  4-91 

error  codes  4-89,4-91, 

Appendix  A 
error  line  4-89 
error  messages    Appendix  A 
error  trapping  4-89,4-91, 

4-178,  4-245 
Esc  key  2-28 
event  trapping 

COM(n)  (communications 

activity)  4-56,4-176 
KEY(n)  4-134,4-182 
PEN  4-185,4-206 
STRIG(n)  (joystick 
button)  4-187,4-275 
exchanging 

variables  4-277 
exclusive  or  3-25 
executable  statements  3-3 
executing  a  program  2-4, 

4-251 
EXP  4-93 

exponential  function  4-93 
exponentiation  3-21 
expressions 

numeric  3-21 

string  3-31 
extended  ASCII  codes  G-6 
extension,  filename  3-36 


F 

false    3-23,  3-25 
FIELD  4-94 
file  control  block  1-5 
file  specification  3-34 
filename    3-34,  3-36 
filename  extension  3-36 
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LPTl:  3-35,4-149,4-160, 

4-161,  1-7 
LPT2:    3-35,  1-7 
LPT  3:    3-35,  1-7 
LSET  4-163 


M 

machine  language 

subroutines    4-34,  4-75, 

4-284,  Appendix  C 
medium  resolution  3-42, 

4-257 
memory  image  4-32 
memory  map  1-2 
MERGE   4-36,  4-165,  B-3 
messages    Appendix  A 
MIDI    4-167,  D-6 
MKI$,  MKS$,  MKD$  4-170, 

B-9 
MOD  3-22 

modulo  arithmetic  3-22 
MOTOR  4-172 
multiple  statements  on  a 

line  3-3 
multiplication  3-21 
music    3-44,  4-209 

N 

NAME  4-173 
naming  files  3-34 
negation  3-21 
NEW  4-174 
NEXT  4-100 

See  also  FOR 
Next  Word    2-2  3 
non-executable  statements 
3-3 


NOT  3-25 
Num  Lock  2-16 
numeric  characters  3-4 
numeric  comparisons  3-23 
numeric  constants  3-9 
numeric  expressions  3-21 
numeric  functions  3-29,4-17 
numeric  keypad  2-15 
numeric  variables  3-13 

o 

OCT$  4-175 
octal  3-10,4-175 
Ok  prompt  2-7 
ONCOM(n)  4-176 
ON  ERROR  4-178 
ONKEY(n)  4-182 
ON  PEN  4-185 
ON  STRIG(n)  4-187 
ON...GOSUB  4-180 
ON.. .GOTO  4-180 
OPEN  (file)    4-189,  B-4, 
B-9 

OPEN  "COM...  4-194,  F-6 
operators 

arithmetic  3-21 

concatenation  3-31 

functions    3-29,  3-32 

logical  3-25 

numeric  3-21 

relational    3-2  3 

string  3-31 
OPTION  BASE  4-200 
options  on  BASIC 

command  2-4 
OR  3-25 
or,  exclusive  3-25 
order  of  execution  3-29 
OUT  4-201 


X-7 


INPUT  #  4-125 
input  and  output  3-33 
input  file  mode    4-189,  B-5 
INPUTS    4-127,  F- 3 
Ins  key  2-26 
insert  mode  2-26 
inserting  characters  2-34 
INSTR  4-129 
INT  4-130 
integer    3-9,  3-11 

converting  to    4-40,  4-99, 
4-130 
integer  division  3-22 
interrupting  program 

execution  2-17 
intrinsic  functions 

See  functions 
invisible  characters  4-51 


J 

joystick    3-45,  4-268 
joystick  button  4-187, 

4-273,  4-275 
jumping  4-113,4-180 


K 

KEY  4-131 
KEY(n)  4-134 
keyboard  2-8 

buffer    See  buffer, 

keyboard 
input  4-119,4-122,4-127, 
4-144 
KILL   4-136,  B- 3 
KYBD:  3-35 


L 

last  point  referenced  3-43 

LEFT$  4-137 

left- justify  4-163 

LEN  4-138 

length  of  file  4-158 

length  of  string  4-104, 

4-138 
LET  4-139 

light  pen  3-45,4-185,4-206 
LINE  4-141 

line  feed    2-32,  4-191,  D-3 
LINE  INPUT  4-144 
LINE  INPUT  #  4-145 
lines 

BASIC  program  3-3 

drawing  in  graphics  4-141 

folding  2-27 

line  numbers    2-7,  3-3, 
4-26,  4-241 

on  screen  3-39 
LIST  3-3,4-147 
list  program  lines  4-149 
listing  files 

on  cassette  4-151 

on  diskette  4-97 
LLIST  4-149 
LOAD   4-150,  B-2 
loading  binary  data  4-29 
LOG   4-15  3 
LOCATE   4-15  5 
LOF  4-158 
LOG  4-159 
logarithm  4-159 
logical  line  2-32 
logical  operators    3-25,  D-3 
loops    4-100,  4-292,  1-14 
LPOS  4-160 
LPRINT  4-161 
LPRINT  USING  4-161 
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s 

SAVE   4-25  3,  B-2 
saving  binary  data  4-32 
screen  3-39 

shifting  4-201 

use  of  3-38 
SCREEN  function  4-255 
SCREEN  statement  4-257 
SCRN:  3-35 
Scroll  Lock  2-16 
scrolling  3-40 
search  order  for  adapters  1-7 
seeding  random  number 

generator    4-2  36 
segment  of  storage  4-71 
sequential  files    4-189,  B-4 
SGN  4-260 

shifting  screen  image  4-201 
sign  of  number  4-260 
SIN  4-261 
sine  4-261 

single-precision  3-11,4-61 
soft  keys  2-9,4-131 
SOUND  4-262 
sounds    3-44,  4-28,  4-209, 

4-262 
SPACE$  4-265 
spaces    3-6,  D-7 
SPC  4-266 
special  characters  3-5 
specification  of  files  3-34 
specifying  coordinates  3-43 
SQR  4-267 
square  root  4-267 
stack  space  4-44 
starting  BASIC  2-3 
statements  4-8 

I/O  4-13 

non-I/O  4-8 
STICK  4-268 
STOP  4-270 


STR$  4-272 
STRIG    4-27  3 
STRIG(n)  4-275 
string  comparisons  3-24 
string  constants  3-9 
string  descriptor  1-4 
string  expressions  3-31 
string  functions  3-32,4-21, 
D-6 

string  space  2-5,4-44,4-104 
string  variables  3-13 
STRING!  4-276 
subroutines  4-111,4-180, 
111 

subroutines,  machine 

language  4-34,4-75,4-284, 

Appendix  C 
subscripts  3-15,4-77,4-200 
substring  4-137,4-167, 

4-248 
subtraction  3-21 
SWAP  4-277 
switching  displays  1-8 
syntax  diagrams  v 
syntax  errors  2-40 
SYSTEM  4-278 
system  functions 

See  functions 
system  requirements 
Advanced  1-6 
Cassette  1-4 
Disk  1-5 
System  Reset  2-18 


T 

TAB  4-279 

Tab  kev  2-30 

TAN  4-280 

tangent  4-280 

technical  information  1-1 


X-9 


telecommunications 

See  communications 
tempo  table  4-264 
terminating  BASIC  4-278 
text  mode  3-39,4-257 
THEN  4-116 
TIME$  4-281 
tips    I- 10 
trace  4-283 
trigonometric  functions 

arctangent  4-25 

cosine  4-60 

sine  4-261 

tangent  4-280 
TROFF  4-283 
TRON  4-283 
true    3-23,  3-25 
truncation  4-99,4-130 
truncation  of  program 

lines  2-36 
two's  complement  3-27,3-28 
type  declaration 

characters  3-14 
typewriter  keyboard  2-10 

U 

underflow   A- 7 
underlined  characters  4-51 
uppershift  2-12 
user  workspace    2-5,  4-44, 
4-104 

user-defined  functions  4-68 
using  the  screen  3-38 
USR  4-75,4-284,014 


V 

VAL  4-285 
variables  3-12 

names  3-12 

storage  of  1-3 
VARPTR    4-286,  1-3 
versions  1-3 
visual  page 
See  display  pages 

w 

WAIT  4-290 
WEND  4-292 
WHILE  4-292 
WIDTH  4-294 
word    2-2  3 

workspace  2-5,4-44,4-104 
WRITE  4-298 
WRITE  #  4-299 

X 

XOR  3-25 
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